Register your agent: the technical reference

Registration adopts an agent that is already deployed. AMC stores metadata about it, checks it is reachable, and never pushes code or a definition to it. For the step-by-step UI walkthrough, see Register agents and workflows. This page covers what each field does underneath.

Fields

The resource id

AMC derives a stable resource id (orchestratorWorkflowId) from the registration and sends it as orchestratorWorkflowId on every POST /runs.

A tenant can register a resource once. The uniqueness key is the adapter, the endpoint host (with its port when it isn't the default), and the resource id. A second registration of the same resource returns 409 already_registered.

The health check

On register, and on any update that changes the endpoint, path segments, the SDK flag, or authentication, AMC checks the resource before it saves anything. A key is checked inline first, so a rejected key is never stored.

A failed check returns 422 with error set to unreachable or access_not_granted, and nothing is saved. The check runs only at registration time: AMC does not re-probe on a schedule.

Managed identity rules

• •Foundry: leave Resource scope blank (AMC uses https://ai.azure.com/.default) or set https://cognitiveservices.azure.com/.default. Grant AMC's identity a least-privilege role on the project first.
• •Custom endpoints: only a Tenant Admin or Super Admin can register one with managed identity (others get 403 managed_identity_requires_tenant_admin). The endpoint must be https, the scope must be an api:// application ID URI, and the installation must have approved that host and audience pair. Otherwise use an API key. See Endpoint and authentication.

Import from Foundry

Import from Foundry registers every agent and workflow in one Foundry project at once. You supply the project endpoint (not an agent URL), one department for all of them, and the authentication AMC uses to list and later run the project. AMC lists the project's catalog, and that listing is the access check.

• •Each new resource is created with source Auto-discovered. Its kind comes from the catalog type: types ending in -agent become agents, the rest workflows.
• •Re-running is safe. Resources already registered keep their department, sensitivity and owner; only their catalog type is refreshed. Nothing is removed for agents that left the project.
• •Import needs workflow-level rights in the department, so an Agent Manager can't import.

Update, deactivate, delete

• •Kind and adapter can't change. Changing the endpoint re-runs the health check; in key mode, a changed endpoint needs the key again.
• •Leaving the input contract or declared steps out of an update keeps the stored ones.
• •Deactivate archives the resource and deletes its stored key. Delete removes it with all its run history. Both are refused with 409 run_in_progress while a run depends on it.

The registration API

The Agents page is a client of these endpoints. They need a signed-in user with the matching permission.

{
  "name": "Invoice Summarizer",
  "kind": "workflow",
  "adapter": "flight-director",
  "departmentId": "finance",
  "endpoint": "https://invoices.contoso.com/amc",
  "usesAmcSdk": true,
  "authMode": "key",
  "key": "<your-agent-api-key>",
  "isSensitive": false,
  "inputContract": {
    "parameters": [
      { "name": "invoiceId", "type": "string", "required": true, "description": "Invoice number" },
      { "name": "ownerEmail", "type": "string", "required": false, "role": "assignee" }
    ]
  },
  "declaredSteps": [
    { "key": "fetch", "name": "Fetch invoice", "order": 1 },
    { "key": "summarize", "name": "Summarize", "order": 2 }
  ]
}