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

All endpoints on this page are [User+Key]. API keys use agents:read, agents:write, agents:delete, and agents:run scopes as appropriate.

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

string

required

Tenant whose agents to list.

curl "$AUTOSAGE_URL/agents?tenant_id=TENANT_ID" \
  -H "Authorization: Bearer $AUTOSAGE_KEY"

List recent agent chats

GET /agents/recent-chats

string

required

Tenant whose agent chats to list.

number

Maximum number to return, from 1 to 50.

Create an agent

POST /agents Creation validates the full configuration and publishes version 1.

string

required

Tenant that owns the agent.

string

required

Human-readable agent name.

string

required

The outcome the agent should pursue.

string

required

Behavioral and output guidance.

string

required

Supported model identifier.

string

required

Knowledge base used for retrieval. This choice is fixed after creation.

boolean

Allow web search during runs.

boolean

Allow durable-memory behavior when tenant and knowledge-base settings permit it.

string[]

Connected apps the agent may use.

string[]

IDs of MCP servers already registered for the organization.

object[]

Skill attachments, each with skill_id and mode always or auto.

object[]

Delegates, each identified by agent_id.

object[]

Custom HTTP tool definitions. Secret header values are encrypted and masked when read back.

string

Subject bound to an API-key-created agent for connected apps and durable-memory isolation.

object

Optional schedule draft. Supported modes are manual, daily, weekly, monthly, custom, and cron.

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

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

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.

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.

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

Copy an agent

POST /agents/:id/copy

string

Optional name for the copy.

string

Optional destination knowledge base.

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.

Schedules run on cron-style cadences. See Scheduling for UTC behavior and supported recurrence patterns.

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.

string

required

Message to send to the agent.

string

Existing agent chat to continue. Omit it to start a new run and chat.

string

Optional model override for this turn.

string

External end-user subject for API-key calls.

string[]

Skills to load for this message.

string[]

Additional delegates available for this message.

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.

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, including ping, agent_thought, final_response, sources, tokens, done, and error.

Next steps

Agent lifecycle

Understand versions, pinned runs, schedules, and terminal states.

Build an agent

Create and invoke an agent end to end.

Agent configuration

Learn how tools, skills, connected apps, and delegates combine.

Chat streaming

Consume runtime events safely.

Get started

Core concepts

Lifecycles

Guides

API reference

Endpoints

List agents

List recent agent chats

Create an agent

Get an agent

Check connected-app readiness

Update agent metadata

Deploy a new version

Copy an agent

Archive an agent

Enable or disable a schedule

List and inspect runs

Stop a run

Send an agent message

Stream an agent message

Next steps

Agent lifecycle

Build an agent

Agent configuration

Chat streaming

​Endpoints

​List agents

​List recent agent chats

​Create an agent

​Get an agent

​Check connected-app readiness

​Update agent metadata

​Deploy a new version

​Copy an agent

​Archive an agent

​Enable or disable a schedule

​List and inspect runs

​Stop a run

​Send an agent message

​Stream an agent message

​Next steps

Agent lifecycle

Build an agent

Agent configuration

Chat streaming

Endpoints

List agents

List recent agent chats

Create an agent

Get an agent

Check connected-app readiness

Update agent metadata

Deploy a new version

Copy an agent

Archive an agent

Enable or disable a schedule

List and inspect runs

Stop a run

Send an agent message

Stream an agent message

Next steps