Skip to content
Customer documentation

Agents and connections

View MarkdownRead the plain-text version ↗Agent indexBrowse all documentation ↗

Add an HTTP chat adapter

Current beta consoleLocal adapter: customer developer; console onboarding: Owner/AdminVerified 2026-11-13 · Isolated local QA + public HTTPSVerification details

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

Section titled “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, 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 explain both options; the Caddy alternative is source-reviewed rather than walkthrough-tested.
  • If public hosting is unavailable, use SDK local evaluations instead. The callback and its provider credentials can remain in your own process.

1. Download and start the service

Section titled “1. Download and start the service”
  1. Download the complete example, extract it, and enter its http-agent directory. The archive includes the server, callback, request, preflight, matching dataset and hosting recipe.
  2. Run:
Shell
python3 --version
python3 server.py --host 127.0.0.1 --port 8765 --callback demo_agent:answer
  1. Keep that process running. In a second terminal in the same directory, check health and chat:
Shell
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

Section titled “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. Use the generated https://…trycloudflare.com origin; it needs no account or domain. Keep both processes running. Quick Tunnel limits
  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
  4. From another machine/network, run the README’s authenticated HTTPS curl checks and:
Shell
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

Section titled “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.
The downloadable adapter uses Martian HTTP chat. Keep session management empty for this stateless example; enter the adapter bearer privately after this step. Open full size
  1. Follow Save and validate → Validate connection, then review the approval conditions and choose Approve connection. See connection onboarding for those exact screens.
  2. 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.
Real HTTPS validation and owner approval are saved. This verifies connectivity and approval; target execution is checked by the three-record evaluation. Open full size

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 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

Section titled “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

Section titled “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, run the three-record evaluation, or use the SDK callback alternative.