> ## 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. # Create an agent > Creates a new agent. The server assigns the UUIDv7 `id`. ## OpenAPI ````yaml /agentic/auto-generated-openapi-v2.yml post /agentic/agents openapi: 3.1.0 info: title: Corti Agent API v2 version: 2.0.0 summary: Manage agents and converse with them over the A2A v1.0 protocol. description: > Version 2 of the Corti Agents REST API. ## What's new in v2 - **Unified `connectors`** — a single, flat, discriminated array replaces the v1 split between `experts`, `mcpServers`, and sub-agents. The envelope is extensible: new connector kinds (`a2a`, `openapi`, `custom`) slot in behind the `type` discriminator without breaking changes. - **Clean CRUD verbs** — `POST` creates, `GET` fetches/lists, `PATCH` performs a *true* partial update, `DELETE` removes. v1's PATCH was effectively a PUT. - **First-class metadata** — `visibility`, `model`, `lifecycle` (now a body field, not a query param), and free-form `labels`. ## A2A v1.0 only The conversational surface speaks **A2A protocol version `1.0` exclusively** (both the `JSONRPC` and `HTTP+JSON` bindings). The deprecated v0.3 binding from v1 is intentionally not carried forward. Per A2A §3.6, clients MUST send the `A2A-Version` header (`Major.Minor`, e.g. `1.0`) on every request to the `/a2a/*` surface, or supply it as the `A2A-Version` query parameter. This surface implements `1.0` only; an absent header is treated as `1.0`. Patch versions MUST NOT be sent. The server echoes the negotiated version in the `A2A-Version` response header. ## Partial updates (PATCH) `PATCH` uses **JSON Merge Patch** semantics (RFC 7386), served under the `application/merge-patch+json` media type: - **Omit a field** → left unchanged. - **`null`** → cleared / reset to its default. - **Arrays** (e.g. `connectors`) → *replaced wholesale*, never merged. To mutate a single connector without replacing the whole array, use the `/connectors` sub-resource endpoints. ## Streaming (Server-Sent Events) The streaming A2A surfaces — `message/stream`, `tasks/subscribe`, and the streaming JSON-RPC methods — respond with `text/event-stream`. The `text/event-stream` media type carries a sequence of Server-Sent Events; the attached schema describes a single event frame. Every event's `data` field is a string carrying a JSON document (`contentMediaType: application/json`); `contentSchema` declares the parsed payload (`StreamResponse` for the `HTTP+JSON` binding, `JSONRPCResponse` for the `JSONRPC` binding). The optional `id` field carries the SSE event id used for resumption via the `Last-Event-ID` request header. contact: name: Corti API Support url: https://corti.ai email: support@corti.ai license: name: Proprietary url: https://corti.ai/terms termsOfService: https://corti.ai/terms servers: - url: https://api.{environment}.corti.app/v2/ description: Corti regional API gateway variables: environment: default: eu enum: - eu - us description: Deployment region. security: - bearerAuth: [] tenantHeader: [] tags: - name: Agents description: Create, read, update, and delete agents. - name: Agent Card description: A2A-compliant agent discovery cards. - name: A2A description: Converse with an agent over the A2A v1.0 protocol. - name: Connectors description: Manage the connectors attached to an agent. - name: Usage description: Bucketed invocation history for an agent. - name: Contexts description: Conversational contexts and their tasks. - name: Registry description: Discoverable, pre-built connectors offered by the platform. - name: Artifacts description: Retrieve artifacts produced by tasks. - name: Feedback description: Collect human or automated feedback on tasks and messages. paths: /agentic/agents: post: tags: - Agents summary: Create an agent description: Creates a new agent. The server assigns the UUIDv7 `id`. operationId: AgentsCreate requestBody: required: true description: The agent to create. content: application/json: schema: $ref: '#/components/schemas/AgentsCreateRequest' examples: coder: $ref: '#/components/examples/AgentCreateExample' responses: '201': description: Agent created. headers: Location: description: Canonical URL of the created agent. schema: type: string format: uri content: application/json: schema: $ref: '#/components/schemas/AgentsResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' x-codeSamples: - lang: csharp label: C# .NET SDK source: | using Corti.Agentic; using Corti; var client = new CortiClient( "TENANT_NAME", CortiClientEnvironment.Eu, new CortiClientAuth.ClientCredentials("client_id", "client_secret") ); await client.Agentic.Agents.CreateAsync( new AgenticAgentsCreateRequest { Name = "coder", Description = "Returns ICD-10 codes for a clinical encounter.", SystemPrompt = "Respond with only the ICD-10 code.", Model = "corti-default", Visibility = AgentsVisibility.Private, Lifecycle = AgentsLifecycle.Persistent, Connectors = new List() { new CommonRegistryConnectorCreate { Name = "pubmed-expert" }, new CommonMcpConnectorCreate { Name = "policybot", Url = "https://mcp.example.com", Auth = new CommonConnectorAuth { Type = CommonConnectorAuthType.Oauth2, Scope = "read:policies", RedirectUrl = "https://app.corti.ai/oauth/callback", }, }, new CommonSchemaConnectorCreate { Name = "submit_code", Description = "Submit the final ICD-10 code for the encounter along with a confidence score.", Schema = new Dictionary() { { "type", "object" }, { "properties", new Dictionary() { { "code", new Dictionary() { { "description", "The selected ICD-10 code." }, { "type", "string" }, } }, { "confidence", new Dictionary() { { "maximum", 1 }, { "minimum", 0 }, { "type", "number" }, } }, } }, { "required", new List() { "code" } }, }, Transition = CommonSchemaConnectorCreateTransition.Complete, }, }, Labels = new Dictionary() { { "team", "coding" }, { "env", "prod" } }, } ); - lang: javascript label: JavaScript SDK source: | import { CortiClient, CortiEnvironment } from "@corti/sdk"; const client = new CortiClient({ environment: CortiEnvironment.Eu, auth: { clientId: "YOUR_CLIENT_ID", clientSecret: "YOUR_CLIENT_SECRET" }, tenantName: "YOUR_TENANT_NAME" }); await client.agentic.agents.create({ name: "coder", description: "Returns ICD-10 codes for a clinical encounter.", systemPrompt: "Respond with only the ICD-10 code.", model: "corti-default", visibility: "private", lifecycle: "persistent", connectors: [{ type: "registry", name: "pubmed-expert" }, { type: "mcp", name: "policybot", url: "https://mcp.example.com", auth: { type: "oauth2", scope: "read:policies", redirectUrl: "https://app.corti.ai/oauth/callback" } }, { type: "schema", name: "submit_code", description: "Submit the final ICD-10 code for the encounter along with a confidence score.", schema: { "type": "object", "properties": { "code": { "type": "string", "description": "The selected ICD-10 code." }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "code" ] }, transition: "complete" }], labels: { "team": "coding", "env": "prod" } }); components: schemas: AgentsCreateRequest: type: object description: >- Request body for creating an agent. The server currently ignores `visibility` and `labels`; they are accepted but not persisted. required: - name properties: name: type: string minLength: 1 maxLength: 128 description: Human-readable, unique-per-tenant agent name. examples: - coder description: type: string maxLength: 4096 description: Free-form agent description. examples: - Returns ICD-10 codes for a clinical encounter. systemPrompt: type: string description: System prompt prepended to every invocation. examples: - Respond with only the ICD-10 code. model: type: string description: Tenant default if omitted. examples: - corti-default maxLoops: type: integer format: int32 minimum: 1 maximum: 100 description: >- Caps the orchestrator's ReAct loop iterations per run. Server default 10 if omitted. examples: - 10 visibility: $ref: '#/components/schemas/AgentsVisibility' default: private lifecycle: $ref: '#/components/schemas/AgentsLifecycle' default: ephemeral connectors: type: array items: $ref: '#/components/schemas/CommonConnectorCreateRequest' default: [] description: Connectors to attach at creation. Defaults to an empty array. labels: $ref: '#/components/schemas/AgentsLabels' additionalProperties: false AgentsResponse: type: object description: A configured agent — its metadata, model, and attached connectors. required: - id - name - visibility - lifecycle - maxLoops - connectors - createdAt - updatedAt - createdBy properties: id: $ref: '#/components/schemas/CommonAgentIDValue' name: type: string minLength: 1 maxLength: 128 description: Human-readable, unique-per-tenant agent name. description: type: - string - 'null' maxLength: 4096 description: Free-form agent description shown to users and in tooling. systemPrompt: type: - string - 'null' description: System prompt prepended to every invocation. model: type: - string - 'null' description: >- Model identifier. Tenant default if omitted or `null`. **Open question** — in the current implementation a model is configured per *expert*, not per *agent* (`Expert.modelName`), and an `Agent` has no model field at all. The desired end state is that there is **no distinction between an expert and an agent**, so `model` lives uniformly on this resource. Until that convergence lands, the precedence of an agent-level `model` over a connector/expert-level override is undecided and MUST be resolved before this field ships. examples: - corti-default x-open-question: expert-vs-agent-model-placement maxLoops: type: integer format: int32 minimum: 1 maximum: 100 description: >- Effective cap on the orchestrator's ReAct loop iterations per run. Always present: agents created without `maxLoops` report the server default (10). examples: - 10 visibility: $ref: '#/components/schemas/AgentsVisibility' lifecycle: $ref: '#/components/schemas/AgentsLifecycle' connectors: type: array items: $ref: '#/components/schemas/CommonConnectorResponse' description: Connectors attached to the agent, discriminated by `type`. labels: $ref: '#/components/schemas/AgentsLabels' createdAt: type: string format: date-time readOnly: true description: When the agent was created. updatedAt: type: string format: date-time readOnly: true description: When the agent was last updated. createdBy: $ref: '#/components/schemas/AgentsUserIDValue' readOnly: true description: Principal (user or service principal) that created the agent. expiresAt: type: - string - 'null' format: date-time readOnly: true description: >- When the agent expires; `null` means it does not expire. Ephemeral agents get a 24h expiry at creation time; persistent agents never expire. examples: - id: agt.0192f4c8-2c5a-7b3e-9f1a-3c8d6e2b7a40 name: coder description: Returns ICD-10 codes for a clinical encounter. systemPrompt: Respond with only the ICD-10 code. model: corti-default maxLoops: 10 visibility: private lifecycle: persistent connectors: - id: con.0192f4c8-7baf-7083-a46f-81d2bd70cf95 type: registry name: pubmed-expert labels: team: coding env: prod createdAt: '2026-05-19T12:00:00Z' updatedAt: '2026-05-19T12:00:00Z' createdBy: usr.0192f4c8-8bc0-7194-8570-92e3ce81d0a6 expiresAt: null AgentsVisibility: type: string description: | - `private` — creator / service principal only. - `unlisted` — usable by ID, hidden from list results. - `public` — listed tenant-wide. enum: - private - unlisted - public example: private AgentsLifecycle: type: string description: | - `ephemeral` — short-lived; expired automatically. - `persistent` — retained until explicitly deleted. enum: - ephemeral - persistent default: ephemeral CommonConnectorCreateRequest: description: Same envelope as `Connector` but without the server-generated `id`. oneOf: - $ref: '#/components/schemas/CommonRegistryConnectorCreate' - $ref: '#/components/schemas/CommonMcpConnectorCreate' - $ref: '#/components/schemas/CommonAgentConnectorCreate' - $ref: '#/components/schemas/CommonA2AConnectorCreate' - $ref: '#/components/schemas/CommonSchemaConnectorCreate' discriminator: propertyName: type mapping: registry: $ref: '#/components/schemas/CommonRegistryConnectorCreate' mcp: $ref: '#/components/schemas/CommonMcpConnectorCreate' agent: $ref: '#/components/schemas/CommonAgentConnectorCreate' a2a: $ref: '#/components/schemas/CommonA2AConnectorCreate' schema: $ref: '#/components/schemas/CommonSchemaConnectorCreate' AgentsLabels: type: object description: >- Free-form `string → string` metadata for filtering and organisation. Not used for routing or auth. additionalProperties: type: string maxLength: 256 propertyNames: type: string pattern: ^[a-zA-Z0-9._/-]{1,128}$ maxProperties: 64 examples: - team: coding env: prod CommonAgentIDValue: type: string format: agent-id description: >- Agent identifier. Accepts `agt.` or a bare UUIDv7 on input; always returned prefixed. pattern: ^(agt\.)?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ examples: - agt.0192f4c8-2c5a-7b3e-9f1a-3c8d6e2b7a40 CommonConnectorResponse: description: A connector attached to an agent, discriminated by `type`. oneOf: - $ref: '#/components/schemas/CommonRegistryConnectorProvisioned' - $ref: '#/components/schemas/CommonMcpConnector' - $ref: '#/components/schemas/CommonAgentConnector' - $ref: '#/components/schemas/CommonA2AConnector' - $ref: '#/components/schemas/CommonSchemaConnector' discriminator: propertyName: type mapping: registry: $ref: '#/components/schemas/CommonRegistryConnectorProvisioned' mcp: $ref: '#/components/schemas/CommonMcpConnector' agent: $ref: '#/components/schemas/CommonAgentConnector' a2a: $ref: '#/components/schemas/CommonA2AConnector' schema: $ref: '#/components/schemas/CommonSchemaConnector' AgentsUserIDValue: type: string format: user-id description: >- Principal identifier. Accepts `usr.` or a bare UUIDv7 on input; always returned prefixed. pattern: ^(usr\.)?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ examples: - usr.0192f4c8-8bc0-7194-8570-92e3ce81d0a6 CommonErrorResponse: type: object description: > Corti management-plane error envelope, used by all non-A2A endpoints. - **Standard** — when the error chain contains at least one `PublicError`, `code` and `message` come from the outermost `PublicError` and `details` is merged across the whole chain (outer values take precedence). - **Fallback** — when the chain contains no `PublicError`, the response is a generic `500` carrying a `requestId` for support reference. - **Validation** — a single `PublicError` whose `details.validationErrors` lists the offending fields. Field names use camelCase on the wire (e.g. `requestId`, `howToFix`). The free-form `details` object may carry arbitrary caller-defined keys. Rate limiting (HTTP 429) is not yet implemented; the server does not emit a 429 response. required: - error properties: error: type: object required: - code - message properties: code: type: string description: Stable, machine-readable, SCREAMING_SNAKE_CASE error code. examples: - ASSIGNMENT_CONFLICT - VALIDATION_FAILED - INTERNAL_ERROR message: type: string description: Human-readable explanation. howToFix: type: string description: Optional guidance for the caller to resolve the error. details: type: object description: | Structured context, merged from every `PublicError` in the chain (outer values win). Omitted on the generic fallback response. additionalProperties: true properties: validationErrors: type: array description: Present when `code` is `VALIDATION_FAILED`. items: type: object required: - field - reason properties: field: type: string description: The field that failed validation. reason: type: string description: Why the field failed validation. requestId: type: string description: > Correlation ID from request middleware. Included only on the generic `500` fallback so consumers can quote it in support requests. description: The error object with code, message, and optional details. examples: - error: code: ASSIGNMENT_CONFLICT message: could not complete assignment details: assignment_id: asg_99 expert_id: exp_42 - error: code: VALIDATION_FAILED message: validation failed details: validationErrors: - field: email reason: invalid format - field: name reason: required - error: code: INTERNAL_ERROR message: internal server error requestId: req_abc123 CommonRegistryConnectorCreate: type: object description: Request body for attaching a registry connector. required: - type - name properties: type: const: registry description: Connector discriminator; always `registry`. name: type: string description: Registry connector name. examples: - pubmed-expert enabled: type: boolean default: true description: Whether the connector is active for invocations. config: type: object additionalProperties: true description: >- Connector-specific configuration validated against the registry schema. Not yet persisted — the server currently drops `config` for registry connectors on create. additionalProperties: false CommonMcpConnectorCreate: type: object description: Request body for attaching an MCP connector. required: - type - name - url properties: type: const: mcp description: Connector discriminator; always `mcp`. name: type: string description: Display name for the MCP connector. url: type: string format: uri description: MCP server endpoint URL. enabled: type: boolean default: true description: Whether the connector is active for invocations. auth: $ref: '#/components/schemas/CommonConnectorAuth' additionalProperties: false CommonAgentConnectorCreate: type: object description: Request body for attaching an agent connector. required: - type - agentId properties: type: const: agent description: Connector discriminator; always `agent`. agentId: $ref: '#/components/schemas/CommonAgentIDValue' enabled: type: boolean default: true description: Whether the connector is active for invocations. additionalProperties: false CommonA2AConnectorCreate: type: object description: Request body for attaching a remote A2A agent connector. required: - type - url properties: type: const: a2a description: Connector discriminator; always `a2a`. name: type: string description: Optional display name for the remote A2A agent. url: type: string format: uri description: Remote agent A2A endpoint URL. enabled: type: boolean default: true description: Whether the connector is active for invocations. additionalProperties: false CommonSchemaConnectorCreate: type: object description: Request body for attaching a schema connector. required: - type - name - schema properties: type: const: schema description: Connector discriminator; always `schema`. name: type: string description: Schema connector name. description: type: string description: What the tool does. Read by the LLM to decide when to call it. schema: type: object description: JSON Schema defining the tool's output shape. additionalProperties: true transition: type: string enum: - complete - input_required description: If set, calling this tool terminates the loop in the given state. enabled: type: boolean default: true description: Whether the connector is active for invocations. additionalProperties: false CommonRegistryConnectorProvisioned: description: A connector provisioned from a registry entry. allOf: - $ref: '#/components/schemas/CommonConnectorBase' - type: object required: - name properties: type: const: registry description: Connector discriminator; always `registry`. name: type: string description: Registry connector name. examples: - pubmed-expert config: type: object description: >- Connector-specific configuration validated against the registry schema. additionalProperties: true CommonMcpConnector: description: A connector backed by a remote MCP server. allOf: - $ref: '#/components/schemas/CommonConnectorBase' - type: object required: - name - url properties: type: const: mcp description: Connector discriminator; always `mcp`. name: type: string description: Display name for the MCP connector. url: type: string format: uri description: MCP server endpoint URL. auth: $ref: '#/components/schemas/CommonConnectorAuth' CommonAgentConnector: description: A connector that delegates to another agent. allOf: - $ref: '#/components/schemas/CommonConnectorBase' - type: object required: - agentId properties: type: const: agent description: Connector discriminator; always `agent`. agentId: $ref: '#/components/schemas/CommonAgentIDValue' CommonA2AConnector: description: A connector that delegates to a remote A2A agent by endpoint URL. allOf: - $ref: '#/components/schemas/CommonConnectorBase' - type: object required: - url properties: type: const: a2a description: Connector discriminator; always `a2a`. name: type: string description: Optional display name for the remote A2A agent. url: type: string format: uri description: >- The remote agent's A2A endpoint (typically a `.well-known/agent-card.json`). examples: - https://marginalia.polycode.co.uk/.well-known/agent-card.json CommonSchemaConnector: description: A connector backed by a schema definition. allOf: - $ref: '#/components/schemas/CommonConnectorBase' - type: object required: - name - schema properties: type: const: schema description: Connector discriminator; always `schema`. name: type: string description: Schema connector name. Used as the tool name the LLM calls. description: type: string description: What the tool does. Read by the LLM to decide when to call it. schema: type: object description: JSON Schema defining the tool's output shape. additionalProperties: true transition: type: string enum: - complete - input_required description: >- If set, calling this tool terminates the loop in the given state after validating and storing the data part. No further LLM call. CommonConnectorAuth: type: object description: Authentication configuration for an outbound connector. required: - type properties: type: type: string enum: - none - bearer - apiKey - oauth2 - inherit description: | Authentication mechanism. `inherit` forwards the caller's bearer token to the MCP server, which is required for internal MCP gateways that expect the Corti platform token for auth. scope: type: string description: OAuth2 scope requested. redirectUrl: type: string format: uri description: OAuth2 redirect URL. ref: type: string description: >- Reference to a server-side stored secret. Mutually exclusive with inline credentials passed at call time. additionalProperties: false examples: - type: oauth2 scope: read:policies redirectUrl: https://app.corti.ai/oauth/callback CommonConnectorBase: type: object description: Fields common to every connector kind. required: - id - type properties: id: $ref: '#/components/schemas/CommonConnectorIDValue' readOnly: true description: > Server-generated connector identifier (prefixed UUIDv7). Stable across PATCH replacements where the underlying spec is unchanged. Used by observability/HITL to reference a connector unambiguously. type: $ref: '#/components/schemas/CommonConnectorType' enabled: type: boolean default: true description: >- Whether the connector is active for invocations. Only `schema` connectors return this field today; `mcp`, `registry`, `agent`, and `a2a` connectors omit it (treat as enabled). CommonConnectorIDValue: type: string format: connector-id description: >- Connector identifier. Accepts `con.` or a bare UUIDv7 on input; always returned prefixed. pattern: ^(con\.)?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ examples: - con.0192f4c8-7baf-7083-a46f-81d2bd70cf95 CommonConnectorType: type: string description: | The connector discriminator. v2 ships `registry`, `mcp`, `agent`, `a2a`, and `schema`; `openapi` and `custom` are reserved for future minor versions. enum: - registry - mcp - agent - a2a - schema examples: AgentCreateExample: summary: Create a coding agent description: >- A persistent coding agent with a registry expert, an MCP connector, and a schema tool that validates the LLM's structured response against a JSON schema and ends the turn. value: name: coder description: Returns ICD-10 codes for a clinical encounter. systemPrompt: Respond with only the ICD-10 code. model: corti-default visibility: private lifecycle: persistent connectors: - type: registry name: pubmed-expert - type: mcp name: policybot url: https://mcp.example.com auth: type: oauth2 scope: read:policies redirectUrl: https://app.corti.ai/oauth/callback - type: schema name: submit_code description: >- Submit the final ICD-10 code for the encounter along with a confidence score. transition: complete schema: type: object properties: code: type: string description: The selected ICD-10 code. confidence: type: number minimum: 0 maximum: 1 required: - code labels: team: coding env: prod responses: BadRequest: description: The request was malformed. content: application/json: schema: $ref: '#/components/schemas/CommonErrorResponse' Unauthorized: description: Missing or invalid credentials. content: application/json: schema: $ref: '#/components/schemas/CommonErrorResponse' Forbidden: description: The caller is not permitted to perform this action. content: application/json: schema: $ref: '#/components/schemas/CommonErrorResponse' Conflict: description: The request conflicts with the current state of the resource. content: application/json: schema: $ref: '#/components/schemas/CommonErrorResponse' UnprocessableEntity: description: The request was well-formed but semantically invalid. content: application/json: schema: $ref: '#/components/schemas/CommonErrorResponse' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: OAuth 2.0 / OIDC bearer token. tenantHeader: type: apiKey in: header name: Tenant-Name description: The tenant the request operates within. ````