Core concepts

This page adds Corti-specific detail on top of the core A2A concepts. For the canonical definition of these concepts, see the A2A documentation on Core Concepts and Components. The Agentic Framework uses a set of core concepts that define how agents, connectors, and external systems interact. Understanding these building blocks is essential for developing on the Corti platform and for integrating your own systems using the A2A protocol.

Core actors

At Corti, these actors map to concrete products and integrations:

User: A clinician, contact-center agent, knowledge worker, or an automated service in your environment. The user initiates a request that requires assistance from one or more Corti-powered agents.
A2A Client (Client Agent): The application that calls Corti. This is your application or server. The client initiates communication using the A2A protocol and orchestrates how results are used in your product.
A2A Server (Remote Agent): A Corti agent that exposes an HTTP endpoint implementing the A2A protocol. It receives requests from clients, processes tasks, and returns results or status updates.

Prefixed UUIDs

All resource identifiers in v2 use type-prefixed UUIDv7 format. The prefix indicates the resource type, making IDs self-documenting and easy to distinguish in logs and traces:

Prefix	Resource	Example
`agt.`	Agent	`agt.0192f4c8-2c5a-7b3e-9f1a-3c8d6e2b7a40`
`con.`	Connector	`con.0192f4c8-7baf-7083-a46f-81d2bd70cf95`
`ctx.`	Context	`ctx.0192f4c8-3d6b-7c4f-a02b-4d9e7f3c8b51`
`task.`	Task	`task.0192f4c8-4e7c-7d50-b13c-5eaf8a4d9c62`
`msg.`	Message	`msg.0192f4c8-5f8d-7e61-924d-6fb09b5ead73`
`art.`	Artifact	`art.0192f4c8-6a9e-7f72-a35e-70c1ac6fbe84`
`fb.`	Feedback	`fb.0192f4c8-7e2a-7b3c-9d4e-5f6a7b8c9d01`
`usr.`	User / principal	`usr.0192f4c8-8bc0-7194-8570-92e3ce81d0a6`

On input, you can send either a prefixed or bare UUIDv7. The server always returns prefixed IDs in responses.

Fundamental communication elements

The following elements are fundamental to A2A communication and how Corti uses them:

Agent card

A JSON metadata document describing an agent’s identity, capabilities, endpoint, skills, and supported protocol bindings. Served at the standard .well-known/agent-card.json location without authentication.Key purpose: Enables discovery and understanding of how to call an agent securely and effectively. See Agent cards.

Task

A stateful unit of work initiated by a message, with a unique ID and defined lifecycle. Tasks have states (submitted, working, completed, failed, canceled, input-required, auth-required, rejected), a history of messages, and can produce artifacts.Key purpose: Powers long-running operations in Corti (for example, document generation or multi-step workflows) and enables tracking and collaboration. See Task lifecycle.

Message

A single turn of communication between a client and an agent, containing content and a role (ROLE_USER or ROLE_AGENT). Messages have a messageId (prefixed UUIDv7), ordered parts, optional referenceTaskIds, and metadata.Key purpose: Carries instructions, clinical context, user questions, and agent responses between your application and agents.

Part

The fundamental content container used within messages and artifacts. A part has text, file, or data properties. Unlike v1, v2 parts do not use a kind discriminator.Key purpose: Lets Corti exchange text, structured JSON, and files in a consistent way across agents and tools.

Artifact

A named output generated by an agent during a task (for example, a document, coding result, or structured data). An artifact has an artifactId, an optional name, and one or more parts.Key purpose: Represents concrete results such as SOAP notes, call summaries, coding suggestions, or other structured outputs.

Context

A server-generated identifier (contextId) that logically groups related tasks, messages, and artifacts, providing context across a series of interactions.Key purpose: Enables you to associate multiple tasks with a single patient encounter, call, or workflow, ensuring continuity and proper scoping of shared knowledge. See Context and memory.

Connector

A typed integration attached to an agent that provides tools and data sources. Connectors replace v1’s experts, MCP servers, and sub-agents with a unified model.Key purpose: Lets agents retrieve information, call external tools, and delegate work. See Connectors.

Agent metadata

Agents in v2 carry first-class metadata that controls visibility, lifecycle, model selection, and organization:

Field	Type	Default	Description
`description`	string	none	Human-readable description of the agent
`systemPrompt`	string	none	System prompt that guides the agent’s reasoning and behavior
`visibility`	enum	`private`	Who can use the agent: `private` (creator only), `unlisted` (usable by ID, hidden from lists), `public` (listed tenant-wide)
`lifecycle`	enum	`ephemeral`	How long the agent persists: `ephemeral` (short-lived, expired automatically) or `persistent` (retained until explicitly deleted)
`model`	string	tenant default	Model identifier for the agent
`labels`	object	none	Free-form `string` to `string` metadata for filtering and organization (max 64 keys)

The visibility and labels fields are in private preview — accepted by the API but not yet persisted. All agents are returned as visibility: "private" and labels are never returned.

The model field is supported in the v2 API. Model precedence over connector-level models is being finalized. See the migration guide if you are migrating from v1 where model was configured per-expert.

Messages and parts

A message represents a single turn of communication between a client and an agent. It includes:

messageId: A prefixed UUIDv7 (e.g. msg.0192f4c8-...)
role: Either ROLE_USER (sent by the client) or ROLE_AGENT (sent by the agent)
parts: An ordered list of content parts
referenceTaskIds: Optional list of task IDs this message references
extensions: Optional URIs of A2A extensions that contributed to this message
metadata: Free-form metadata, including Corti’s $timestamp (RFC 3339) for timing

Part types

A part is the fundamental content container. In v2, parts use property-based discrimination (no kind field):

Text part: Contains plain text in the text property
File part: Contains a file in the file property with name, mimeType, uri, or inline bytes (base64)
Data part: Contains structured JSON in the data property

{
  "text": "Generate a summary of this patient encounter"
}

{
  "data": {
    "patientId": "pat_12345",
    "encounterDate": "2026-05-19",
    "chiefComplaint": "Chest pain"
  }
}

Artifacts

An artifact represents a tangible output or concrete result generated by an agent during task processing. Unlike general messages, artifacts are the actual deliverables. An artifact has:

artifactId: A prefixed UUIDv7 (e.g. art.0192f4c8-...)
name: An optional human-readable name
parts: Content parts containing the artifact data

In Corti, artifacts typically correspond to business outputs such as clinical notes, extracted facts, coding suggestions, or generated documents.

Agent response: Task or message

The agent response can be a new Task (when the agent needs to perform a long-running operation) or a Message (when the agent can respond immediately):

For quick operations (for example, a short completion or a classification), the agent responds with a Message
For longer workflows (for example, generating a full clinical document, coordinating multiple connectors, or waiting on downstream systems), the agent responds with a Task that you can monitor and retrieve artifacts from

See Task lifecycle for details on task states and streaming.

Next steps

Read about connectors, the unified integration model
Learn about agent cards for A2A discovery
Follow the quickstart to create your first agent

Quickstart

Concepts

Guides

Reference

Registry Connectors

Agent SDK

v1 Documentation (archived)

Core actors

Prefixed UUIDs

Fundamental communication elements

Agent metadata

Messages and parts

Part types

Artifacts

Agent response: Task or message

Next steps

​Core actors

​Prefixed UUIDs

​Fundamental communication elements

​Agent metadata

​Messages and parts

​Part types

​Artifacts

​Agent response: Task or message

​Next steps

Core actors

Prefixed UUIDs

Fundamental communication elements

Agent metadata

Messages and parts

Part types

Artifacts

Agent response: Task or message

Next steps