# Register your agent: the technical reference

Agent Mission Control developer docs > Overview

> Every registration field, how AMC derives the resource id, what the health check does, and how Foundry import works.

**Before you start:** A deployed, reachable agent. Tenant Admin, Department Manager, or Agent Manager (agents only).

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](https://www.agentmissioncontrol.ai/guide/register-agents/). This page covers what each field does underneath.

## Fields

| UI label | API field | What it does |
| --- | --- | --- |
| **Name** | `name` | Required. The display name people see on the **Agents** page and on runs. |
| **Kind** | `kind` | `workflow` or `agent`. Immutable. An Agent Manager can register only `agent`. |
| **Adapter** | `adapter` | `foundry` (**Azure AI Foundry**) or `flight-director` (**Flight Director / custom**). Immutable. |
| **Department** | `departmentId` | Required in the form. Scopes who can see and run it. Must be a department you can write to. |
| **This resource uses the AMC SDK** | `usesAmcSdk` | Custom adapter only. Lets you register without path segments. |
| **Endpoint URL** | `endpoint` | Required. The base URL. For Foundry, the agent URL (it contains `/agents/<name>`). For custom, the URL AMC appends `/health`, `/runs` and so on to. |
| **Path segments** | `pathSegments` | Custom adapter only, required unless you use the AMC SDK. Joined with `/` to form the resource id. They don't change the URLs AMC calls. |
| **Authentication** | `authMode` | `same-tenant-mi` (**Managed Identity (same tenant)**) or `key` (**API key**). |
| **Customer tenant id** | `customerTenantId` | Optional, managed identity only. Stored with the registration. |
| **Resource scope** | `resourceScope` | Managed identity only. The audience AMC requests a token for. Required for custom endpoints (an `api://<app-id>/.default` scope). |
| **API key** | `key` | Key mode only. Write-only: stored in Key Vault, never returned, presented as the `api-key` header. |
| **Mark this resource as sensitive** | `isSensitive` | Hides runs from people without a grant to the resource. |
| **Allow this resource's artifacts to start runs** | `artifactsMayStartRuns` | Off by default. Lets HTML artifacts this resource produces start runs, as the viewer, after the viewer confirms. |
| **Artifact retention (days)** | `artifactRetentionDays` | Optional. Blank uses the tenant default. |
| **Input contract** | `inputContract` | Optional. The parameters a run accepts. See [Declare run parameters](https://www.agentmissioncontrol.ai/developers/byo-input-contract/). |
| **Declared steps** | `declaredSteps` | Optional. The step plan, in order: `key`, `name`, `description`. Each `key` should equal the `stepId` your agent reports. |

## The resource id

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

| Registration | Resource id |
| --- | --- |
| Foundry | The agent name: the path segment after `/agents/` in the endpoint URL. |
| Custom, with path segments | The segments joined with `/`, for example `finance/invoice-summarizer`. |
| Custom, no path segments (AMC SDK) | The endpoint's lowercase host and path, trailing slash removed, for example `invoices.contoso.com/amc`. |

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.

| Adapter | Check | Result |
| --- | --- | --- |
| Custom | `GET <endpoint>/health` with the registration's credential. One attempt, 5 second timeout, redirects not followed. | `2xx`: **Healthy**. `401` or `403`: **Access not granted**. Any other status (including `503`), a timeout, or a connection failure: **Unreachable**. |
| Foundry | A catalog lookup of the agent in its Foundry project. Foundry endpoints have no `/health`. | Found: **Healthy**. Auth failure: **Access not granted**. Anything else: **Unreachable**. |

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](https://www.agentmissioncontrol.ai/developers/byo-endpoint-and-auth/).

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

| Method and path | Purpose |
| --- | --- |
| `GET /api/adapters` | The adapter catalog: each adapter's required inputs and supported auth modes. |
| `POST /api/registrations` | Register. Returns `201` with the registration and `health: "healthy"`. |
| `PUT /api/registrations/{id}` | Update. Re-checks health when the endpoint or auth changed. |
| `POST /api/registrations/import` | Import a Foundry project. |
| `POST /api/registrations/{id}/deactivate` | Deactivate. |
| `POST /api/registrations/{id}/reassign-owner` | Reassign the accountable owner. |
| `DELETE /api/registrations/{id}` | Delete. |

`POST /api/registrations (custom adapter, key mode)`
```json
{
  "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 }
  ]
}
```

> **Note:** The `role` field on an input parameter is accepted by the API but not offered in the registration form. Set it through the API when you need AMC to route a run to the person named in an input. See [Declare run parameters](https://www.agentmissioncontrol.ai/developers/byo-input-contract/).

## Related

- [The integration contract](https://www.agentmissioncontrol.ai/developers/integration-contract/)
- [Endpoint and authentication](https://www.agentmissioncontrol.ai/developers/byo-endpoint-and-auth/)
- [Declare run parameters](https://www.agentmissioncontrol.ai/developers/byo-input-contract/)
- [How agents connect to AMC](https://www.agentmissioncontrol.ai/developers/how-agents-connect/)

---
Source: https://www.agentmissioncontrol.ai/developers/register-your-agent/ · Last updated 2026-10-21 · Full index: https://www.agentmissioncontrol.ai/llms.txt