> ## 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 and configure an agent

> Learn how to create, list, get, patch, and delete agents using the v2 Agentic API.

This guide shows you how to create and configure an agent with connectors, metadata, and labels. You will learn the full agent CRUD lifecycle using the v2 Agentic API.

## Prerequisites

* An access token or client credentials
* Your tenant name
* Basic understanding of [connectors](/agentic/connectors) and [core concepts](/agentic/core-concepts)

## Create a minimal agent

The simplest agent has just a name. All other fields are optional:

```bash theme={null}
# Replace these with your values
ENVIRONMENT="<eu-or-us>"
TENANT="<your-tenant-name>"
TOKEN="<your-access-token>"

curl -X POST "https://api.${ENVIRONMENT}.corti.app/v2/agentic/agents" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Tenant-Name: ${TENANT}" \
  -H "Content-Type: application/json" \
  -d '{ "name": "my-agent" }'
```

The response includes the agent's `id` (a prefixed UUIDv7), `visibility` (default: `private`), `lifecycle` (default: `ephemeral`), and an empty `connectors` array.

## Create an agent with connectors

To make an agent useful, attach connectors at creation time:

```bash theme={null}
curl -X POST "https://api.${ENVIRONMENT}.corti.app/v2/agentic/agents" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Tenant-Name: ${TENANT}" \
  -H "Content-Type: application/json" \
  -d '{
    "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": "coding-expert"},
      {"type": "mcp", "name": "policybot", "url": "https://mcp.example.com"},
      {
        "type": "schema",
        "name": "submit_code",
        "description": "Submit the final ICD-10 code with a confidence score.",
        "transition": "complete",
        "schema": {
          "type": "object",
          "properties": {
            "code": {"type": "string"},
            "confidence": {"type": "number", "minimum": 0, "maximum": 1}
          },
          "required": ["code"]
        }
      }
    ],
    "labels": {"team": "coding", "env": "prod"}
  }'
```

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

<Note>The `model` field is supported in the v2 API. In the current implementation, a model is configured per connector rather than per agent; the precedence of an agent-level `model` over connector-level models is being finalized.</Note>

## List agents

Filter agents by visibility, lifecycle, labels, or free-text search:

<Warning>The `visibility`, `lifecycle`, `label`, and `q` listing filters are in private preview — accepted by the API but silently ignored. Only `pageSize` and `pageToken` are functional.</Warning>

```bash theme={null}
# All public agents
curl "https://api.${ENVIRONMENT}.corti.app/v2/agentic/agents?visibility=public" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Tenant-Name: ${TENANT}"

# Persistent agents with label team=coding
curl "https://api.${ENVIRONMENT}.corti.app/v2/agentic/agents?lifecycle=persistent&label=team%3Dcoding" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Tenant-Name: ${TENANT}"

# Free-text search
curl "https://api.${ENVIRONMENT}.corti.app/v2/agentic/agents?q=coder" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Tenant-Name: ${TENANT}"
```

## Get a single agent

```bash theme={null}
AGENT_ID="<your-agent-id>"

curl "https://api.${ENVIRONMENT}.corti.app/v2/agentic/agents/${AGENT_ID}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Tenant-Name: ${TENANT}"
```

## Patch an agent

Use JSON Merge Patch to update an agent. Omitted fields are unchanged; `null` clears; `connectors` is replaced wholesale:

```bash theme={null}
curl -X PATCH "https://api.${ENVIRONMENT}.corti.app/v2/agentic/agents/${AGENT_ID}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Tenant-Name: ${TENANT}" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{
    "name": "coder-v2",
    "systemPrompt": "Respond with only the SNOMED CT code.",
    "connectors": [
      {"type": "registry", "name": "coding-expert"}
    ]
  }'
```

<Warning>The `connectors` array in a PATCH replaces the entire list. To modify individual connectors without replacing the whole array, use the [connector sub-resource endpoints](/agentic/guides/manage-connectors).</Warning>

<Warning>The server currently honors only `name`, `description`, `systemPrompt`, `model`, and `connectors` in PATCH requests. The `visibility`, `lifecycle`, and `labels` fields are accepted but not yet persisted.</Warning>

## Delete an agent

```bash theme={null}
curl -X DELETE "https://api.${ENVIRONMENT}.corti.app/v2/agentic/agents/${AGENT_ID}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Tenant-Name: ${TENANT}"
```

<Warning>Deleting a persistent agent is irreversible. Ephemeral agents expire automatically.</Warning>

## Common patterns

### Ephemeral vs. persistent

* **Ephemeral** (`lifecycle: "ephemeral"`): Short-lived agents that expire automatically. Good for one-off tasks and testing.
* **Persistent** (`lifecycle: "persistent"`): Retained until explicitly deleted. Good for production agents.

### Private vs. public

* **Private** (`visibility: "private"`): Only the creator can use the agent.
* **Unlisted** (`visibility: "unlisted"`): Usable by anyone who knows the ID, but hidden from list results.
* **Public** (`visibility: "public"`): Listed tenant-wide.

## Next steps

* Learn how to [send a message](/agentic/guides/send-message) to your agent
* Learn how to [manage connectors](/agentic/guides/manage-connectors) individually
* Read about [connector auth](/agentic/guides/connector-auth) for outbound connectors