Create and configure an agent

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 and core concepts

Create a minimal agent

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

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

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"}
  }'

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.

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.

List agents

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

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.

# 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

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:

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"}
    ]
  }'

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.

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.

Delete an agent

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

Deleting a persistent agent is irreversible. Ephemeral agents expire automatically.

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 to your agent
Learn how to manage connectors individually
Read about connector auth for outbound connectors

Quickstart

Concepts

Guides

Reference

Registry Connectors

Agent SDK

v1 Documentation (archived)

Prerequisites

Create a minimal agent

Create an agent with connectors

List agents

Get a single agent

Patch an agent

Delete an agent

Common patterns

Ephemeral vs. persistent

Private vs. public

Next steps

​Prerequisites

​Create a minimal agent

​Create an agent with connectors

​List agents

​Get a single agent

​Patch an agent

​Delete an agent

​Common patterns

​Ephemeral vs. persistent

​Private vs. public

​Next steps

Prerequisites

Create a minimal agent

Create an agent with connectors

List agents

Get a single agent

Patch an agent

Delete an agent

Common patterns

Ephemeral vs. persistent

Private vs. public

Next steps