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

# Migrate from v1 to v2

> Learn the path changes, experts-to-connectors mapping, PATCH semantics, and A2A protocol changes for migrating from v1 to v2.

This guide helps you migrate from the v1 Agentic Framework API to the v2 API. It covers path changes, the experts-to-connectors mapping, PATCH semantics, A2A protocol changes, and new features.

<Note>The v1 API reference remains available in the API Reference tab as "Agentic APIs v1 (deprecated)". The v1 documentation is preserved in the [v1 archived docs](/agentic/v1/overview).</Note>

## API path changes

All v2 endpoints move under `/v2/agentic/`:

| v1 path                              | v2 path                                                   |
| ------------------------------------ | --------------------------------------------------------- |
| `POST /agents`                       | `POST /v2/agentic/agents`                                 |
| `GET /agents`                        | `GET /v2/agentic/agents`                                  |
| `GET /agents/{id}`                   | `GET /v2/agentic/agents/{id}`                             |
| `PATCH /agents/{id}`                 | `PATCH /v2/agentic/agents/{id}`                           |
| `DELETE /agents/{id}`                | `DELETE /v2/agentic/agents/{id}`                          |
| `GET /agents/{id}/agent-card.json`   | `GET /v2/agentic/agents/{id}/.well-known/agent-card.json` |
| `POST /agents/{id}/v1/message:send`  | `POST /v2/agentic/agents/{id}/a2a/message:send`           |
| `GET /agents/{id}/v1/tasks/{taskId}` | `GET /v2/agentic/agents/{id}/a2a/tasks/{taskId}`          |
| `GET /agents/registry/experts`       | `GET /v2/agentic/registry/connectors`                     |

## Experts to connectors

In v1, the Agentic Framework used three separate concepts: Experts, MCP servers, and sub-agents. v2 unifies all three under the connector model.

| v1 concept | v2 connector type | Example                                                      |
| ---------- | ----------------- | ------------------------------------------------------------ |
| Expert     | `registry`        | `{"type": "registry", "name": "coding-expert"}`              |
| MCP server | `mcp`             | `{"type": "mcp", "name": "policybot", "url": "https://..."}` |
| Sub-agent  | `agent`           | `{"type": "agent", "agentId": "agt.0192f4c8-..."}`           |

### v1 agent creation (with experts)

```json theme={null}
{
  "name": "coder",
  "experts": [{"name": "coding-expert"}]
}
```

### v2 agent creation (with connectors)

```json theme={null}
{
  "name": "coder",
  "connectors": [
    {"type": "registry", "name": "coding-expert"}
  ]
}
```

## PATCH semantics

v1 already used partial-update PATCH semantics: omitted fields were unchanged, and arrays (`experts`, `mcpServers`) were replaced wholesale when provided. v2 adopts **JSON Merge Patch** (RFC 7386), which adds the ability to explicitly clear fields with `null`:

* **Omitted fields**: Unchanged (same as v1)
* **`null`**: Clears the field (new in v2 — in v1, `null` decoded to a nil Go pointer and was treated as "unchanged")
* **`connectors` array**: Replaced wholesale (same as v1's `experts` array)

```json theme={null}
{
  "name": "coder-v2",
  "systemPrompt": null,
  "connectors": [
    {"type": "registry", "name": "coding-expert"}
  ]
}
```

This PATCH renames the agent, clears the system prompt, and replaces the entire connectors array with a single registry connector. All other fields remain unchanged.

<Warning>The `Content-Type` header for PATCH requests is `application/merge-patch+json` in v2.</Warning>

## A2A v0.3 to v1.0

v2 supports A2A v1.0 only. v0.3 is not carried forward to v2 (still available on the v1 API surface). Key changes:

| v1 (A2A v0.3)                         | v2 (A2A v1.0)                                                            |
| ------------------------------------- | ------------------------------------------------------------------------ |
| `role: "user"`                        | `role: "ROLE_USER"`                                                      |
| `kind: "message"` on message envelope | Removed (no `kind` field)                                                |
| `kind: "text"` on parts               | Removed (use `text` property directly)                                   |
| `kind: "data"` on parts               | Removed (use `data` property directly)                                   |
| No `A2A-Version` header               | `A2A-Version: 1.0` header on A2A endpoints (optional, defaults to `1.0`) |
| Single binding (HTTP+JSON)            | Two bindings: JSON-RPC and HTTP+JSON                                     |

### v1 message format

```json theme={null}
{
  "message": {
    "role": "user",
    "parts": [{"kind": "text", "text": "Hello"}],
    "messageId": "msg-001",
    "kind": "message"
  }
}
```

### v2 message format

```json theme={null}
{
  "message": {
    "role": "ROLE_USER",
    "parts": [{"text": "Hello"}],
    "messageId": "msg.0192f4c8-5f8d-7e61-924d-6fb09b5ead73"
  }
}
```

## Removed features

| v1 feature                                                                | v2 replacement                                                                                   |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `?ephemeral=true` query param on agent create                             | `lifecycle: "ephemeral"` in request body                                                         |
| `experts` array on agent create/patch                                     | `connectors` array with `type: "registry"`                                                       |
| `authorizationType` on MCP connectors                                     | `auth.type` in `ConnectorAuth` object                                                            |
| v1 agent card path (`/agent-card.json`)                                   | `.well-known/agent-card.json`                                                                    |
| `agentType` field (expert, orchestrator, interviewing-expert)             | Removed — all agents use the same model; specialization comes from connectors and system prompts |
| `transportType` on MCP connectors (stdio/streamable\_http/sse)            | Removed — MCP connectors use streamable HTTP                                                     |
| Inline expert creation (`type: "new"` with system prompt and MCP servers) | Removed — use `registry` connectors referencing pre-built experts                                |
| `pushNotificationConfig` on message send                                  | Removed (future scope)                                                                           |
| `kind: "task"` and `kind: "file"` on parts                                | Removed (use `text`, `file`, or `data` properties directly)                                      |
| `description` required on agent create                                    | `description` is now optional (only `name` is required)                                          |
| Artifact `description`, `metadata`, `extensions` fields                   | Removed (artifacts now have `artifactId`, `name`, `parts` only)                                  |
| Task states `submitted`, `working`                                        | Renamed to `TASK_STATE_SUBMITTED`, `TASK_STATE_WORKING` (PascalCase enum)                        |

## New features in v2

v2 introduces several new capabilities:

* **Agent metadata**: `visibility` (private, unlisted, public), `lifecycle` (ephemeral, persistent), `model`, `labels`
* **Connector sub-resources**: Individual connector CRUD via `/agents/{id}/connectors` endpoints
* **Contexts API**: List, get, and delete contexts via `/v2/agentic/contexts` endpoints
* **Registry API**: Browse and inspect pre-built connectors via `/v2/agentic/registry/connectors`
* **Usage API**: Agent usage metrics via `/agents/{id}/usage`
* **Feedback API**: Submit, list, and delete feedback via `/contexts/{id}/tasks/{id}/feedback`
* **Trace export**: OpenInference traces via `/contexts/{id}/trace`
* **Agent cards**: Standard `.well-known/agent-card.json` location (requires authentication)
* **Streaming**: `message:stream` and `tasks:subscribe` SSE endpoints
* **Prefixed UUIDv7 IDs**: All resource IDs use type-prefixed format (e.g. `agt.`, `ctx.`, `task.`)
* **JSON-RPC binding**: Alternative to HTTP+JSON for A2A communication

## Next steps

* Read the [v2 overview](/agentic/overview) for the full v2 feature set
* Follow the [quickstart](/agentic/quickstart) to create a v2 agent
* Browse the [v1 archived documentation](/agentic/v1/overview) for reference
* Use the [v1 API reference](/api-reference) (labeled "Agentic APIs v1 (deprecated)") for v1 endpoint details