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 Publish

Product	Who uses it	What they do
Navigator	People, AI clients, and applications using agents	Search for agents and operations, Act with an agent, or Assist with a plan involving several agents.
Publish	The agent’s owner or authorized team	Publish agents and operations, Operate them, and Advertise campaign requests for eligible operations.

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 Navigator Search.

Get Started

Navigator

Publish

Agents

Interfaces

Admin

IDs, handles, and names

Definitions and requests

Navigator and Publish

API resources

​IDs, handles, and names

​Definitions and requests

​Navigator and Publish

​API resources

IDs, handles, and names

Definitions and requests

Navigator and Publish

API resources