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

# Agent SDK overview

> Get started with the Corti Agent SDK for TypeScript and Python, in alpha v2 private preview.

<Warning>
  The Corti Agent SDK is in **alpha v2 private preview**. The API surface may change between releases, and the Python package is still being rebuilt for v2 parity. Do not use it in production without a dedicated support arrangement. Contact [help@corti.ai](mailto:help@corti.ai) to request access.
</Warning>

The Corti Agent SDK (`@corti/agent-sdk` for TypeScript, `corti-agent-sdk` for Python) is a developer-friendly wrapper for building multi-agent systems on the [Agentic Framework](/agentic/overview) v2 API. The TypeScript package is the v2 reference implementation. The Python package is being rebuilt for v2 parity; until then, the two may differ in available features.

The TypeScript package is built on [openapi-ts](https://openapi-ts.dev/) with `openapi-fetch` as its only runtime dependency. The Python package uses [httpx](https://www.python-httpx.org/) with async/await.

## What it provides

* **Agent lifecycle**: create, list, get, update, and delete agents via typed resource clients
* **A2A messaging**: send messages, stream responses, and manage conversation contexts with automatic context ID tracking
* **Connector factories**: build `registry`, `mcp`, `agent`, `a2a`, and `schema` (TypeScript only) connectors with typed factory helpers
* **Multi-agent composition**: deterministic `workflow` pipelines, `parallel` fan-out, and `stateGraph` routing with cycles and typed shared state
* **Structured errors**: typed error classes (`CortiError`, `ManagementError`, `HttpError`, `A2AError`) for both management and A2A planes
* **Extended resources**: contexts, registry, usage, feedback, agent cards, and models

## Prerequisites

* A Corti API tenant with credentials
* **TypeScript**: Node.js 18 or later (uses native `fetch` and `AsyncIterable`)
* **Python**: Python 3.9 or later

The TypeScript package is ESM-only. For CommonJS projects, use dynamic `import()` or set your project to ESM.

## Install

<CodeGroup>
  ```bash title="JavaScript" theme={null}
  npm install @corti/agent-sdk
  ```

  ```bash title="Python" theme={null}
  pip install corti-agent-sdk
  ```
</CodeGroup>

## Quick example

<CodeGroup>
  ```ts title="JavaScript" theme={null}
  import { CortiClient, AgentHandle, connectors } from "@corti/agent-sdk";

  // Replace these with your values
  const REGISTRY_NAME = "@corti/medical-coding";
  const TENANT = "<your-tenant-name>";
  const TOKEN = "<your-access-token>";

  const client = new CortiClient({ token: TOKEN, tenant: TENANT });

  const agent = await client.agents.create({
    name: "my-agent",
    description: "Handles medical coding queries",
    connectors: [connectors.registry(REGISTRY_NAME)],
  });

  const handle = new AgentHandle(agent, client);
  const ctx = handle.createContext();
  const reply = await ctx.sendText("ICD-10 code for hypertension?");

  console.log(reply.text); // "The ICD-10 code is I10."
  ```

  ```python title="Python" theme={null}
  import asyncio
  from corti_agent_sdk import CortiClient, AgentsClient, connectors

  # Replace these with your values
  CLIENT_ID = "<your-client-id>"
  CLIENT_SECRET = "<your-client-secret>"
  ENVIRONMENT = "<eu-or-us>"
  REGISTRY_NAME = "@corti/medical-coding"
  TENANT = "<your-tenant-name>"


  async def main():
      async with CortiClient(
          tenant_name=TENANT,
          environment=ENVIRONMENT,
          auth={"client_id": CLIENT_ID, "client_secret": CLIENT_SECRET},
      ) as client:
          agents = AgentsClient(client)

          agent = await agents.create(
              name="my-agent",
              description="Handles medical coding queries",
              connectors=[connectors.registry(name=REGISTRY_NAME)],
          )

          ctx = agent.create_context()
          reply = await ctx.send_text("ICD-10 code for hypertension?")
          print(reply.text)  # "The ICD-10 code is I10."


  asyncio.run(main())
  ```
</CodeGroup>

## Decision guide

| You want to...                                                 | Use                                  |
| -------------------------------------------------------------- | ------------------------------------ |
| Send one message and get one reply                             | `agent.run(text)` or `ctx.sendText`  |
| Hold a multi-turn conversation                                 | `agent.createContext()` + `sendText` |
| Resume a thread from a previous process or session             | `agent.getContext(contextId)`        |
| Stream tokens as the agent writes them                         | `ctx.streamMessage([...])`           |
| Run a fixed pipeline of agents (A to B to C)                   | `workflow([...])`                    |
| Run agents concurrently on the same input                      | `parallel([...])`                    |
| Conditionally branch, loop, or share typed state across agents | `stateGraph<State>()`                |
| Attach an MCP server, sub-agent, or registry connector         | `connectors.*` in `create({...})`    |

**Rule of thumb:** start with `workflow`. Only reach for `stateGraph` when you need cycles or branching that depends on accumulated state.

## Next steps

<CardGroup cols={2}>
  <Card title="Core concepts" icon="book-open" href="/agentic/agent-sdk/concepts">Learn about the client, agents, contexts, connectors, message responses, and streaming.</Card>
  <Card title="Multi-agent composition" icon="workflow" href="/agentic/agent-sdk/composition">Build workflows, fan out in parallel, and route with state graphs.</Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="API reference" icon="code" href="/agentic/agent-sdk/api-reference">Full method and type reference for both languages.</Card>
  <Card title="Common pitfalls" icon="triangle-alert" href="/agentic/agent-sdk/common-pitfalls">Avoid the most frequent mistakes when using the SDK.</Card>
</CardGroup>