The integration contract
The checklist every agent meets, whatever the build path, so AMC can start, watch, govern and price it.
Before you startRead [How agents connect](/developers/how-agents-connect/) first.View as Markdown
These are the obligations AMC places on any agent. On the custom adapter you meet each one with an HTTP endpoint. On Foundry you meet the same obligations through the Responses stream and its markers; each Foundry section shows how.
| # | Obligation | What AMC needs | Detail |
|---|---|---|---|
| 1 | Endpoint | One absolute http(s) base URL. AMC calls fixed paths under it (/health, /runs, /runs/{id}/...). | Endpoint and authentication |
| 2 | Authentication | Accept the credential AMC presents: an api-key header (key mode) or an Entra bearer token for your app's api:// audience (managed identity). | Endpoint and authentication |
| 3 | Health check | GET /health answers 2xx when ready, 401/403 when the credential is wrong. AMC calls it when you register or change the endpoint or auth. | Register your agent |
| 4 | Invocation | POST /runs accepts { orchestratorWorkflowId, versionId, inputs, idempotencyKey }, starts the work in the background, and returns a run id at once. | Start and cancel a run |
| 5 | Input contract | Declare the run parameters at registration. Read them from the flat inputs string map. | Declare run parameters |
| 6 | Run status | GET /runs/{id}/status returns the run status (running, human_intervention, completed, failed, cancelled) and every step. A completed run can add outcome: "partial" to report that part of the work wasn't done. | Run status and steps |
| 7 | Steps | Each step has a stable stepId, a status, timestamps, and content readable at GET /runs/{id}/steps/{stepId}/content. | Run status and steps |
| 8 | Token and cost reporting | Per-step inputTokens, outputTokens, cachedInputTokens and model; run totals at GET /runs/{id}/tokens, with costUsd if you price it yourself. | Report tokens and cost |
| 9 | Human in the loop | To ask a person, report run status human_intervention with the question on the waiting step, and accept the answer at POST /runs/{id}/messages. | Ask a person mid-run |
| 10 | Failure | A failed run ends with status failed and a failureReason people can act on. Spend accrued before the failure is still reported. | Errors and timeouts |
| 11 | Cancel | POST /runs/{id}/cancel stops the run and reports cancelled. | Start and cancel a run |
| 12 | Live events (recommended) | GET /runs/{id}/events streams typed events as SSE for people watching the run. | Run status and steps |
Rules that cause silent errors
- Use camelCase JSON keys exactly as documented. AMC reads them case-insensitively, but a misspelled key reads as empty, with no error.
- Report the input/output split and the model. With only
tokenCountand nocostUsd, ROI falls back to a flat per-token estimate. A step with nomodel, or a model AMC has no rate for, prices at AMC's default rate. - Don't report a status AMC doesn't know. An unknown run status is treated as
waiting, which the run page shows as Intervention. - Keep run state after the run ends. AMC reads step lists and step content from your agent whenever someone opens the run.
Related
Last updated 2026-10-21