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

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.

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)

{
  "name": "coder",
  "experts": [{"name": "coding-expert"}]
}

v2 agent creation (with connectors)

{
  "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)

{
  "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.

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

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

{
  "message": {
    "role": "user",
    "parts": [{"kind": "text", "text": "Hello"}],
    "messageId": "msg-001",
    "kind": "message"
  }
}

v2 message format

{
  "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 for the full v2 feature set
Follow the quickstart to create a v2 agent
Browse the v1 archived documentation for reference
Use the v1 API reference (labeled “Agentic APIs v1 (deprecated)”) for v1 endpoint details

Quickstart

Concepts

Guides

Reference

Registry Connectors

Agent SDK

v1 Documentation (archived)

API path changes

Experts to connectors

v1 agent creation (with experts)

v2 agent creation (with connectors)

PATCH semantics

A2A v0.3 to v1.0

v1 message format

v2 message format

Removed features

New features in v2

Next steps

​API path changes

​Experts to connectors

​v1 agent creation (with experts)

​v2 agent creation (with connectors)

​PATCH semantics

​A2A v0.3 to v1.0

​v1 message format

​v2 message format

​Removed features

​New features in v2

​Next steps

API path changes

Experts to connectors

v1 agent creation (with experts)

v2 agent creation (with connectors)

PATCH semantics

A2A v0.3 to v1.0

v1 message format

v2 message format

Removed features

New features in v2

Next steps