> ## Documentation Index
> Fetch the complete documentation index at: https://darwin.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Core concepts

> Understand agents, operations, and their IDs, handles, and names.

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.

```json theme={null}
{
  "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](/docs/act/messaging) 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](/docs/studio/publish) or [Navigator Search](/docs/search/quickstart).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.