> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autosage.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Create, version, schedule, run, copy, and archive agents.

Agents are saved, versioned runtime configurations tied to one knowledge base. Use these endpoints to manage their lifecycle and run them synchronously or over Server-Sent Events (SSE).

<Note>
  All endpoints on this page are **\[User+Key]**. API keys use `agents:read`, `agents:write`, `agents:delete`, and `agents:run` scopes as appropriate.
</Note>

## Endpoints

| Method   | Path                           | Description                                 | Auth        |
| -------- | ------------------------------ | ------------------------------------------- | ----------- |
| `GET`    | `/agents`                      | List agents for a tenant                    | \[User+Key] |
| `GET`    | `/agents/recent-chats`         | List recent agent chats                     | \[User+Key] |
| `POST`   | `/agents`                      | Create an agent and version 1               | \[User+Key] |
| `GET`    | `/agents/:id`                  | Get an agent                                | \[User+Key] |
| `GET`    | `/agents/:id/integrations`     | Check connected-app readiness               | \[User+Key] |
| `PATCH`  | `/agents/:id`                  | Update name or status without a new version | \[User+Key] |
| `POST`   | `/agents/:id/deploy`           | Deploy a new version                        | \[User+Key] |
| `POST`   | `/agents/:id/copy`             | Copy or fork an agent                       | \[User+Key] |
| `DELETE` | `/agents/:id`                  | Archive an agent                            | \[User+Key] |
| `POST`   | `/agents/:id/schedule/enable`  | Enable its schedule                         | \[User+Key] |
| `POST`   | `/agents/:id/schedule/disable` | Disable its schedule                        | \[User+Key] |
| `GET`    | `/agents/:id/runs`             | List runs                                   | \[User+Key] |
| `GET`    | `/agents/:id/runs/:runId`      | Get a run                                   | \[User+Key] |
| `POST`   | `/agents/:id/runs/:runId/stop` | Stop a run                                  | \[User+Key] |
| `POST`   | `/agents/:id/messages`         | Run or continue an agent                    | \[User+Key] |
| `POST`   | `/agents/:id/messages/stream`  | Run or continue an agent over SSE           | \[User+Key] |

## List agents

`GET /agents`

<ParamField query="tenant_id" type="string" required>
  Tenant whose agents to list.
</ParamField>

```bash theme={null}
curl "$AUTOSAGE_URL/agents?tenant_id=TENANT_ID" \
  -H "Authorization: Bearer $AUTOSAGE_KEY"
```

## List recent agent chats

`GET /agents/recent-chats`

<ParamField query="tenant_id" type="string" required>
  Tenant whose agent chats to list.
</ParamField>

<ParamField query="limit" type="number">
  Maximum number to return, from 1 to 50.
</ParamField>

## Create an agent

`POST /agents`

Creation validates the full configuration and publishes version 1.

<ParamField body="tenant_id" type="string" required>
  Tenant that owns the agent.
</ParamField>

<ParamField body="name" type="string" required>
  Human-readable agent name.
</ParamField>

<ParamField body="goal" type="string" required>
  The outcome the agent should pursue.
</ParamField>

<ParamField body="instructions" type="string" required>
  Behavioral and output guidance.
</ParamField>

<ParamField body="model_id" type="string" required>
  Supported model identifier.
</ParamField>

<ParamField body="selected_knowledge_base_id" type="string" required>
  Knowledge base used for retrieval. This choice is fixed after creation.
</ParamField>

<ParamField body="web_search_enabled" type="boolean">
  Allow web search during runs.
</ParamField>

<ParamField body="use_memory_enabled" type="boolean">
  Allow durable-memory behavior when tenant and knowledge-base settings permit it.
</ParamField>

<ParamField body="enabled_integration_slugs" type="string[]">
  Connected apps the agent may use.
</ParamField>

<ParamField body="enabled_mcp_ids" type="string[]">
  IDs of MCP servers already registered for the organization.
</ParamField>

<ParamField body="attached_skills" type="object[]">
  Skill attachments, each with `skill_id` and mode `always` or `auto`.
</ParamField>

<ParamField body="callable_agents" type="object[]">
  Delegates, each identified by `agent_id`.
</ParamField>

<ParamField body="custom_tools" type="object[]">
  Custom HTTP tool definitions. Secret header values are encrypted and masked when read back.
</ParamField>

<ParamField body="external_subject_id" type="string">
  Subject bound to an API-key-created agent for connected apps and durable-memory isolation.
</ParamField>

<ParamField body="schedule" type="object">
  Optional schedule draft. Supported modes are `manual`, `daily`, `weekly`, `monthly`, `custom`, and `cron`.
</ParamField>

```bash theme={null}
curl -X POST "$AUTOSAGE_URL/agents" \
  -H "Authorization: Bearer $AUTOSAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "TENANT_ID",
    "name": "Support specialist",
    "goal": "Resolve support questions from approved documentation.",
    "instructions": "Answer concisely and cite the relevant source.",
    "model_id": "MODEL_ID",
    "selected_knowledge_base_id": "KB_ID",
    "web_search_enabled": false,
    "use_memory_enabled": true
  }'
```

<Warning>
  The knowledge base is immutable after creation. Use the copy endpoint to place equivalent configuration on another knowledge base.
</Warning>

For the complete nested schemas for schedules, tools, skills, and delegates, use `/swagger`.

## Get an agent

`GET /agents/:id`

Returns the current agent configuration, schedule, version, and recent run information. Secret custom-tool headers are masked.

## Check connected-app readiness

`GET /agents/:id/integrations`

Returns the connection status of the apps enabled for the identity that will run the agent, including whether scheduled runs are supported.

## Update agent metadata

`PATCH /agents/:id`

Updates `name` or `status` (`active` or `archived`) without creating a new version.

```bash theme={null}
curl -X PATCH "$AUTOSAGE_URL/agents/AGENT_ID" \
  -H "Authorization: Bearer $AUTOSAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Support specialist — EMEA" }'
```

## Deploy a new version

`POST /agents/:id/deploy`

Accepts the same complete configuration as agent creation. A successful deploy increments the version; a failed validation leaves the previous version unchanged.

<Info>
  In-flight runs stay pinned to the version they started with. New runs use the newly deployed version.
</Info>

## Copy an agent

`POST /agents/:id/copy`

<ParamField body="name" type="string">
  Optional name for the copy.
</ParamField>

<ParamField body="selected_knowledge_base_id" type="string">
  Optional destination knowledge base.
</ParamField>

The copy is a new agent. Its schedule is copied in a disabled state so it cannot fire unexpectedly.

## Archive an agent

`DELETE /agents/:id`

Archives the agent and disables its schedule while preserving its run history.

## Enable or disable a schedule

`POST /agents/:id/schedule/enable` enables the saved non-manual schedule. `POST /agents/:id/schedule/disable` pauses it. Neither action creates a new agent version.

<Note>
  Schedules run on cron-style cadences. See [Scheduling](/agents/scheduling) for UTC behavior and supported recurrence patterns.
</Note>

## List and inspect runs

`GET /agents/:id/runs` returns the agent's runs. `GET /agents/:id/runs/:runId` returns one run and verifies that it belongs to the agent in the path.

Run status can be `queued`, `running`, `completed`, `failed`, or `cancelled`.

## Stop a run

`POST /agents/:id/runs/:runId/stop`

Stops an in-flight run. Partial output already generated remains available with the run and its chat. Stopping a terminal run returns a conflict response.

## Send an agent message

`POST /agents/:id/messages`

Starts a run, or continues the run associated with `chat_id`, and returns a complete JSON response.

<ParamField body="message" type="string" required>
  Message to send to the agent.
</ParamField>

<ParamField body="chat_id" type="string">
  Existing agent chat to continue. Omit it to start a new run and chat.
</ParamField>

<ParamField body="model" type="string">
  Optional model override for this turn.
</ParamField>

<ParamField body="external_subject_id" type="string">
  External end-user subject for API-key calls.
</ParamField>

<ParamField body="skill_ids" type="string[]">
  Skills to load for this message.
</ParamField>

<ParamField body="delegate_agent_ids" type="string[]">
  Additional delegates available for this message.
</ParamField>

```bash theme={null}
curl -X POST "$AUTOSAGE_URL/agents/AGENT_ID/messages" \
  -H "Authorization: Bearer $AUTOSAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Summarize the current refund policy." }'
```

The response includes `chat_id`, `run_id`, and run data. Reuse `chat_id` to continue the same run.

## Stream an agent message

`POST /agents/:id/messages/stream`

Accepts the same body as the non-streaming endpoint and returns SSE. Response headers include `X-Chat-Id` and, for a new run, `X-Run-Id`.

```bash theme={null}
curl -N -X POST "$AUTOSAGE_URL/agents/AGENT_ID/messages/stream" \
  -H "Authorization: Bearer $AUTOSAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Investigate the most common support issue." }'
```

The stream uses the same runtime events documented in [Chat & streaming](/developers/guides/chat-and-stream), including `ping`, `agent_thought`, `final_response`, `sources`, `tokens`, `done`, and `error`.

## Next steps

<CardGroup cols={2}>
  <Card title="Agent lifecycle" icon="arrows-spin" href="/developers/lifecycles/agent-lifecycle">
    Understand versions, pinned runs, schedules, and terminal states.
  </Card>

  <Card title="Build an agent" icon="robot" href="/developers/guides/build-an-agent">
    Create and invoke an agent end to end.
  </Card>

  <Card title="Agent configuration" icon="sliders" href="/agents/configuring">
    Learn how tools, skills, connected apps, and delegates combine.
  </Card>

  <Card title="Chat streaming" icon="bolt" href="/developers/guides/chat-and-stream">
    Consume runtime events safely.
  </Card>
</CardGroup>