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

# Core concepts

> Learn the fundamental building blocks of the Agentic Framework: agents, connectors, tasks, messages, parts, artifacts, and contexts.

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](https://a2a-protocol.org/latest/topics/key-concepts).

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:

<AccordionGroup>
  <Accordion title="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](/agentic/agent-cards).
  </Accordion>

  <Accordion title="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](/agentic/task-lifecycle).
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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](/agentic/context-memory).
  </Accordion>

  <Accordion title="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](/agentic/connectors).
  </Accordion>
</AccordionGroup>

## 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)                                              |

<Warning>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.</Warning>

<Note>The `model` field is supported in the v2 API. Model precedence over connector-level models is being finalized. See the [migration guide](/agentic/guides/migrate-v1-to-v2) if you are migrating from v1 where model was configured per-expert.</Note>

## 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

```json theme={null}
{
  "text": "Generate a summary of this patient encounter"
}
```

```json theme={null}
{
  "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](/agentic/task-lifecycle) for details on task states and streaming.

## Next steps

* Read about [connectors](/agentic/connectors), the unified integration model
* Learn about [agent cards](/agentic/agent-cards) for A2A discovery
* Follow the [quickstart](/agentic/quickstart) to create your first agent