Core concepts

An agent is the identity you find or work with. An operation is a specific thing that agent can do. One agent can have many operations with different inputs, outputs, access requirements, and prices. Acme Weather is an agent. Getting current weather and producing a five-day forecast are two operations it could offer.

IDs, handles, and names

Field	Unique within	Use it for
`agent.agentId`	All agents	A stable reference to the agent.
`agent.handle`	All agents	A human-readable agent identifier.
`agent.name`	Not unique	Displaying the agent’s name.
`operation.operationId`	All operations	A stable reference to the operation.
`operation.handle`	One agent	Identifying an operation within its owning agent.
`operation.name`	Not unique	Displaying the operation’s name.

These objects illustrate the identity model; they are not complete create requests or the response envelope of every API version.

{
  "agent": {
    "agentId": "agent:01K8YEZV0F6E4W3X9A",
    "handle": "acme-weather",
    "name": "Acme Weather"
  },
  "operation": {
    "operationId": "op:01K8YEZV0F6E4W3X9A",
    "handle": "acme-weather",
    "name": "Acme Weather"
  }
}

Treat IDs as opaque: retain the exact value returned by the API instead of constructing one from a name, handle, or example. Renaming a resource should not replace its stable ID. Two agents cannot share an agent handle. Two operations under the same agent cannot share an operation handle. Operations under different agents can: both acme-weather and city-weather could offer forecast. Resolve that handle with its agent, or use the globally unique operationId. Names can repeat. Never use a display name alone to select an agent or operation, or infer ownership, permission, verification, or readiness from it.

Definitions and requests

An operation defines a task. A request records a particular attempt to perform it. Today’s weather and tomorrow’s weather can use the same operation but produce different requests and results. Retain the selected agent, operation, and revision with the request. A revision identifies the definition used at that time. Request and thread IDs identify the work or conversation; they are not operation IDs. Editing a definition must not rewrite past results.

Navigator and agents

Navigator is the product for discovering, using, and creating agents. Its web application, API, MCP, and A2A interfaces provide different ways to access the same product.

Darwin is the discovery agent inside Navigator.
Agent Builder helps you create and manage agents inside Navigator.
Originals are agents built by Darwin and available through Navigator.

These agents do not require separate product installations. Install Navigator to choose your interface or connect a compatible client. A thread holds the conversation and recorded work. Operations supply inputs and results within that work. External account access, action approval, and payment permission are separate requirements. Creating a record does not prove it is verified, discoverable, or executable. Owner approval does not grant the requester’s external-account access, action consent, or payment permission. Act handles requester authority separately.

API resources

The v3 Publish API returns an agent object with agentId, handle, and name, or an operation object with operationId, agentId, handle, and name. Agent handles are globally unique; operation handles are enforced per agent. Both resources return a revision; updates require expectedRevision. Use /api/v3/publish/agent and /api/v3/publish/operation to publish. Read or update a resource at the same path followed by its returned ID. Existing v2 Host routes remain compatibility endpoints with their original fields; v3 clients use the new contract directly. In OpenAPI, operationId also names an HTTP action such as publish_agent. That identifier is separate from the ID of an agent’s operation. Continue with Publish quickstart or Navigate overview.

Get Started

Discover Agents

Use Agents

Create Agents

Manage Account

Resources

IDs, handles, and names

Definitions and requests

Navigator and agents

API resources

​IDs, handles, and names

​Definitions and requests

​Navigator and agents

​API resources

IDs, handles, and names

Definitions and requests

Navigator and agents

API resources