# Add an HTTP chat adapter

> Run a complete callback-backed HTTP service, preflight its contract, and provide the public HTTPS endpoint required by console onboarding.

Source: [Web version](https://docs.martiansecurity.ai/agents/http-adapter/)

> **Page qualification:** Current beta console · Local adapter: customer developer; console onboarding: Owner/Admin · Verified 2026-11-13 · Isolated local QA + public HTTPS. [Verification details](https://raw.githubusercontent.com/MorningHQ/martian-security-docs/main/public/markdown/reference/verification.md).

Use this example when your application has a local response function but does not yet expose the HTTP chat contract required by console-triggered assessments and dataset Evals. The result is a running service that accepts Martian’s JSON request and returns your callback’s text in `content`.

The supplied callback is deterministic teaching code, not an LLM. It recognizes the first-evaluation tutorial’s three fixed questions. Its passing checks establish connectivity and scoring wiring, not production agent quality or attack resistance.

## Before you start

-   Local preflight needs Python **3.12 or newer** and a terminal. No third-party Python package or provider account is required.
-   Hosted onboarding requires an **Owner** or **Admin**, the [current qualification status](https://raw.githubusercontent.com/MorningHQ/martian-security-docs/main/public/markdown/reference/verification.md), and a public HTTPS host reachable from Martian’s servers. Localhost is not reachable merely because the console opens in your browser.
-   For the tested disposable HTTPS recipe, use Docker Desktop and outbound internet access. Alternatively, supply a dedicated Linux host, public DNS, reachable ports 80/443 and Caddy. The [complete hosting instructions](https://raw.githubusercontent.com/MorningHQ/martian-security-docs/main/public/examples/http-agent/README.md) explain both options; the Caddy alternative is source-reviewed rather than walkthrough-tested.
-   If public hosting is unavailable, use [SDK local evaluations](https://raw.githubusercontent.com/MorningHQ/martian-security-docs/main/public/markdown/sdk/evaluations.md) instead. The callback and its provider credentials can remain in your own process.

## 1\. Download and start the service

1.  [Download the complete example](https://raw.githubusercontent.com/MorningHQ/martian-security-docs/main/public/examples/http-agent/martian-http-agent.zip), extract it, and enter its `http-agent` directory. The archive includes the server, callback, request, preflight, matching dataset and hosting recipe.
2.  Run:

```sh
python3 --version
python3 server.py --host 127.0.0.1 --port 8765 --callback demo_agent:answer
```

3.  Keep that process running. In a second terminal in the same directory, check health and chat:

```sh
curl --fail-with-body --silent --show-error http://127.0.0.1:8765/health
curl --fail-with-body --silent --show-error \
  --header 'Content-Type: application/json' \
  --data-binary @request.json http://127.0.0.1:8765/chat
python3 preflight.py --origin http://127.0.0.1:8765
```

Expect HTTP 200, health `status: ok`, and `content: READY`. If the adapter bearer is already configured, use the authenticated curl form in the README; the Python preflight reads that environment credential automatically.

The wire request is a JSON object containing `campaign_id`, `target_id`, `conversation_id`, `message`, `turn`, `reset` and `action_id`. `POST /chat` accepts `Content-Type: application/json`; the response is a JSON object with nonempty string `content`. A raw provider completion URL with another schema needs this adaptation.

## 2\. Protect and host the endpoint

1.  Inject a strong adapter-specific token as `MARTIAN_ADAPTER_TOKEN` and restart the server. `/chat` now requires `Authorization: Bearer ...`; `/health` stays public. This is separate from a Martian API key and a provider key.
2.  For the disposable tutorial on Docker Desktop, keep the protected Python service running locally and start the [exact tested tunnel command in the README](https://raw.githubusercontent.com/MorningHQ/martian-security-docs/main/public/examples/http-agent/README.md). Use the generated `https://…trycloudflare.com` origin; it needs no account or domain. Keep both processes running. [Quick Tunnel limits](https://developers.cloudflare.com/tunnel/get-started/quick-tunnels/)
3.  For a durable host instead, follow `Caddyfile.example`: use your public DNS name and satisfy its DNS/network prerequisites. Keep Python on the host’s loopback address behind ingress. [Caddy HTTPS requirements](https://caddyserver.com/docs/automatic-https)
4.  From another machine/network, run the README’s authenticated HTTPS curl checks and:

```sh
python3 preflight.py --origin https://YOUR-PUBLIC-HOST
```

Expect the same verified health/READY responses with certificate validation enabled. A private address, local certificate, login page, redirect or timeout does not satisfy this prerequisite. A successful external preflight still needs Martian’s own connection validation and actual target execution.

Keep a tutorial tunnel running through onboarding and evaluation. If its hostname changes, onboard a replacement connection with the new URLs, validate and approve it, and select that registration for future runs. Saved endpoint URLs cannot be edited in place.

## 3\. Register the real HTTPS address

1.  Open **Agents → Onboard agent** and enter the name, declared purpose and other required registration fields.
2.  Select **Martian HTTP chat**. Set **Agent chat endpoint** to `https://YOUR-PUBLIC-HOST/chat` and **Health endpoint (optional)** to `https://YOUR-PUBLIC-HOST/health`.
3.  For the protected adapter, choose **Bearer token** and enter the adapter’s credential in **Target credential**. Leave session-management fields empty: this example has no session API or sandbox bindings.

![Teaching HTTP adapter connection form before entering its private bearer.](https://raw.githubusercontent.com/MorningHQ/martian-security-docs/main/public/media/screenshots/agents-http-details.png)

The downloadable adapter uses Martian HTTP chat. Keep session management empty for this stateless example; enter the adapter bearer privately after this step.

4.  Follow **Save and validate → Validate connection**, then review the approval conditions and choose **Approve connection**. See [connection onboarding](https://raw.githubusercontent.com/MorningHQ/martian-security-docs/main/public/markdown/agents/connections.md) for those exact screens.
5.  Confirm **active** and **Ready for assessments**. Refresh and reopen the agent to verify the saved state.

![Approved teaching HTTP adapter, active and ready after refresh.](https://raw.githubusercontent.com/MorningHQ/martian-security-docs/main/public/media/screenshots/agents-ready.png)

Real HTTPS validation and owner approval are saved. This verifies connectivity and approval; target execution is checked by the three-record evaluation.

Connectivity validation reads the supplied health URL; it does not prove that every chat prompt or business workflow succeeds. Import the included `first-evaluation.jsonl`, publish it, select **Default**, and [run your first evaluation](https://raw.githubusercontent.com/MorningHQ/martian-security-docs/main/public/markdown/evals/first-run.md) to exercise the actual POST and retained results. The sample supports stateless endpoint-only testing; a sandbox-backed assessment needs additional customer integration.

## Replace the teaching callback

Create an importable `my_agent.py` with `answer(message: str) -> str`, then start `python3 server.py --callback my_agent:answer`. An async function returning nonempty text also works. Your application/provider calls and credentials stay on the adapter side; Martian authorizes and calls this endpoint using the separate target credential. Configure your provider/network timeouts and the controls your application needs.

This small server has no durable side-effect idempotency, rate limiting, session store or sandbox tool wiring. Use your application’s normal web stack and controls beyond the synthetic tutorial. The full README documents the request fields, errors and deployment prerequisites.

## If preflight or onboarding fails

-   **401**: the adapter token is missing or mismatched. Update the target credential and validate/approve again after rotation.
-   **415/422**: send the JSON content type and all seven request fields. Check that your callback returns nonempty text under `content`.
-   **502** from this example: the callback failed or returned an unsupported value. Inspect your own application privately; the service omits exception details from its public response.
-   TLS/DNS/timeout errors: resolve public reachability before onboarding. Keep certificate checks enabled; a local successful curl does not prove SaaS reachability.
-   Local preflight passed but no app screenshot/walkthrough qualification is recorded above: end-to-end onboarding remains unverified. Do not treat a source example as a deployed product run.

Next, [connect and manage the agent](https://raw.githubusercontent.com/MorningHQ/martian-security-docs/main/public/markdown/agents/connections.md), [run the three-record evaluation](https://raw.githubusercontent.com/MorningHQ/martian-security-docs/main/public/markdown/evals/first-run.md), or use [the SDK callback alternative](https://raw.githubusercontent.com/MorningHQ/martian-security-docs/main/public/markdown/sdk/evaluations.md).