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

# FAQ

> Frequently asked questions about the Agentic Framework.

Common questions and answers to help you get the most out of the Agentic Framework and the underlying A2A-based APIs.

<AccordionGroup>
  <Accordion title="What is the difference between the agent runtime and connectors?">
    The **agent runtime** is the central reasoning layer of the Agentic Framework. It receives user requests, reasons about what needs to be done, and delegates work to connectors. The runtime does not perform specialized work itself. Instead, it plans, selects appropriate connectors, and coordinates their activities to accomplish complex workflows.

    A **connector** is a typed integration that provides tools and data sources to the agent. Connectors replace v1's experts, MCP servers, and sub-agents with a unified model. The runtime composes complex workflows by chaining multiple connectors together.

    In summary: the agent runtime coordinates and delegates; connectors execute specialized work.

    For more details, see [Architecture](/agentic/architecture) and [Connectors](/agentic/connectors).
  </Accordion>

  <Accordion title="What is the difference between A2A and MCP?">
    **A2A (Agent-to-Agent)** is the protocol your application uses to communicate with Corti agents. It handles agent-to-agent communication: sending messages, receiving tasks, streaming responses, and managing the agent lifecycle. A2A is the conversational surface.

    **MCP (Model Context Protocol)** is one of five connector types in v2. When you attach an MCP connector to an agent, the agent can call the MCP server's tools at runtime. MCP handles agent-to-tool interactions.

    In the Agentic Framework: A2A is how clients talk to agents; MCP (as a connector type) is how agents talk to external tool servers. The two protocols complement each other and serve different layers.

    For more information, see [A2A protocol](/agentic/a2a-protocol) and [Connectors](/agentic/connectors).
  </Accordion>

  <Accordion title="When does an agent return a Task vs a Message?">
    The agent response can be a new `Task` (for long-running work) or a `Message` (for quick responses). A Task represents a stateful unit of work with a unique ID and defined lifecycle.

    Tasks are used for:

    * Long-running operations (for example, generating a full clinical document)
    * Multi-step workflows that coordinate multiple connectors
    * Operations that may need to wait on downstream systems
    * Any work that benefits from tracking and monitoring

    Messages (with immediate responses) are used for very quick operations like simple classifications or completions that can be resolved immediately without asynchronous processing.

    For more details, see [Task lifecycle](/agentic/task-lifecycle) and [Core concepts](/agentic/core-concepts).
  </Accordion>

  <Accordion title="What is the difference between a data part and a text part?">
    Use **text parts** for messages that will be directly available to the agent runtime and the LLM. Text part content is immediately available for reasoning and response generation.

    Use **data parts** for structured JSON data that will be stored in memory and accessed through semantic retrieval. Data part content is automatically indexed and stored in the context's memory, enabling retrieval when needed. Data parts are useful for structured data like patient records, clinical facts, workflow parameters, or EHR identifiers.

    You can combine both in a single message: use a text part for the primary instruction or question, and a data part to provide structured context.

    For more details, see [Core concepts](/agentic/core-concepts) and [Context and memory](/agentic/context-memory).
  </Accordion>

  <Accordion title="How does an Artifact differ from a Message?">
    Both `Message` and `Artifact` use the same underlying part primitives, but they serve different roles:

    * **Message** (with `role: "ROLE_AGENT"`): Represents a single turn of communication from the agent. Best for conversational output, intermediate reasoning, clarifications, or status updates.
    * **Artifact**: Represents a tangible, durable output of a task (for example, a SOAP note, coding suggestions, or a generated document). Has its own `artifactId`, name, and parts.

    A useful mental model: **Messages are how agents talk; Artifacts are what they produce.**

    For more details, see [Task lifecycle](/agentic/task-lifecycle).
  </Accordion>

  <Accordion title="What is the best way to pass previous context into a new message?">
    The Agentic Framework provides automatic memory management through contexts. The `contextId` is always created on the server. Send your first message without a `contextId`, and the server returns one in the response. Include that `contextId` in subsequent messages to maintain conversation history automatically.

    You can also pass additional context in each request using data parts to include structured data alongside the automatic memory.

    For comprehensive guidance, see [Context and memory](/agentic/context-memory).
  </Accordion>

  <Accordion title="Can I share data between different contexts?">
    No. Contexts provide strict data isolation. Data can never leak across contexts. Each `contextId` creates a completely isolated conversation scope where messages, tasks, artifacts, and any data within one context are completely inaccessible to agents working in a different context.

    If you need to share information across contexts, you must explicitly pass it via data parts in your messages.

    For more details, see [Context and memory](/agentic/context-memory).
  </Accordion>

  <Accordion title="How does the agent runtime decide which connectors to use?">
    The agent runtime analyzes incoming requests and uses reasoning to determine which connectors are needed. It considers the nature of the request, the available connectors, and their capabilities.

    You can influence connector selection by writing system prompts in the agent configuration. System prompts guide how the runtime reasons about task decomposition and connector selection. The runtime can compose multiple connectors, calling them in sequence or parallel as needed.

    For more information, see [Architecture](/agentic/architecture) and [Connectors](/agentic/connectors).
  </Accordion>

  <Accordion title="What are the visibility levels for agents?">
    Agents have three visibility levels:

    * **`private`** (default): Only the creator can use the agent.
    * **`unlisted`**: Usable by anyone who knows the agent ID, but hidden from list results.
    * **`public`**: Listed tenant-wide, visible to all users in the tenant.

    For more details, see [Create an agent](/agentic/guides/create-agent).
  </Accordion>

  <Accordion title="What is the difference between ephemeral and persistent agents?">
    * **`ephemeral`** (default): Short-lived agents that expire automatically. Good for one-off tasks and testing.
    * **`persistent`**: Retained until explicitly deleted. Good for production agents.

    For more details, see [Create an agent](/agentic/guides/create-agent).
  </Accordion>

  <Accordion title="How does JSON Merge Patch work for agents?">
    v2 uses JSON Merge Patch (RFC 7386) for agent and connector updates. Omitted fields are unchanged (not removed), `null` clears a field, and the `connectors` array is replaced wholesale.

    For example, to rename an agent and clear its system prompt:

    ```json theme={null}
    {
      "name": "coder-v2",
      "systemPrompt": null
    }
    ```

    This leaves all other fields unchanged. See [Create an agent](/agentic/guides/create-agent) for details.
  </Accordion>

  <Accordion title="What are prefixed UUIDs?">
    All resource identifiers in v2 use type-prefixed UUIDv7 format. The prefix indicates the resource type, making IDs self-documenting in logs and traces:

    * `agt.` for agents
    * `con.` for connectors
    * `ctx.` for contexts
    * `task.` for tasks
    * `msg.` for messages
    * `art.` for artifacts

    For more details, see [Core concepts](/agentic/core-concepts).
  </Accordion>

  <Accordion title="What changed from v1 to v2?">
    Key changes in v2 include:

    * Experts, MCP servers, and sub-agents are unified under the connector model
    * API paths move from `/agents` to `/v2/agentic/agents`
    * A2A protocol is upgraded to v1.0 (v0.3 not carried forward to v2, still available on v1)
    * Agents gain `visibility`, `lifecycle`, `model`, and `labels` metadata
    * Contexts, connectors, registry, usage, feedback, traces, and agent cards all have dedicated API endpoints
    * All IDs use prefixed UUIDv7 format
    * PATCH uses JSON Merge Patch semantics

    See the [v1-to-v2 migration guide](/agentic/guides/migrate-v1-to-v2) for a full mapping.
  </Accordion>
</AccordionGroup>