Skip to main content
An agent packages a goal, instructions, a model, and a knowledge base into a reusable worker you can run on demand or on a schedule. This guide takes you from an empty knowledge base to a deployed agent answering questions and completing tasks.

​
Before you start

You need an API key and a knowledge base that already contains processed documents. If you haven’t set one up, follow the quickstart first — it provisions a tenant, a knowledge base, and an uploaded document in a few minutes. 
export AUTOSAGE_KEY="sk_live_your_key_here"
export AUTOSAGE_URL="https://api.autosage.ai/api/v1"

​
Create the agent

POST /agents creates an agent bound to a single knowledge base. Only a few fields are required; the rest let you extend what the agent can do.
​
tenant_id
string
required
The tenant the agent belongs to.
​
name
string
required
A human-readable name for the agent.
​
selected_knowledge_base_id
string
required
The knowledge base the agent draws grounded answers from. This is fixed at creation — see the note below.
​
model_id
string
required
The model that powers the agent’s reasoning and responses.
​
goal
string
required
A short statement of what the agent is for.
​
instructions
string
required
Detailed behavior guidance — tone, format, boundaries, and how to handle edge cases.
​
enabled_integration_slugs
string[]
Connected apps the agent may use (for example a CRM or calendar). Each app must be authenticated first — see below.
​
attached_skills
object[]
Reusable skills, each with a skill_id and mode always or auto.
​
custom_tools
object[]
Custom tool definitions the agent can call.
​
callable_agents
object[]
Other agents this agent may delegate to, each identified by agent_id.
​
schedule
object
An optional schedule to run the agent automatically. Schedules run in UTC.
curl -X POST "$AUTOSAGE_URL/agents" \
  -H "Authorization: Bearer $AUTOSAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "TENANT_ID",
    "name": "Support specialist",
    "selected_knowledge_base_id": "KB_ID",
    "model_id": "MODEL_ID",
    "goal": "Answer customer support questions from the help center.",
    "instructions": "Answer only from the knowledge base. Cite the source passage. If the answer is not covered, say so and suggest contacting support. Keep replies under 150 words.",
    "enabled_integration_slugs": ["zendesk"],
    "attached_skills": [
      { "skill_id": "SKILL_ID", "mode": "auto" }
    ],
    "schedule": {
      "schedule_mode": "cron",
      "schedule_cron": "0 9 * * 1",
      "timezone": "UTC"
    }
  }'
The response includes the new agent’s id. Save it — every later call uses it.
The selected knowledge base is fixed once the agent is created. To point an agent at a different knowledge base, create a copy of the agent with the new knowledge base rather than editing the original. This keeps a running agent’s grounding stable and predictable.
A connected app must be authenticated before you enable it on an agent. Enabling an app that isn’t authenticated leaves the agent unable to use it. Complete the app’s connection flow, then include its slug in enabled_integration_slugs.

​
Deploy your changes

Creating an agent publishes version 1. To change its runtime configuration later, send the complete updated configuration to POST /agents/:id/deploy; a successful deploy publishes the next version. 
curl -X POST "$AUTOSAGE_URL/agents/AGENT_ID/deploy" \
  -H "Authorization: Bearer $AUTOSAGE_KEY" \
  -H "Content-Type: application/json" \
  --data @agent-config.json
Deploy again any time you change the agent’s goal, instructions, model, tools, or schedule.

​
Run the agent

Send the agent a message to run it. Choose non-streaming for a single complete response, or streaming for live progress and final content. 
curl -X POST "$AUTOSAGE_URL/agents/AGENT_ID/messages" \
  -H "Authorization: Bearer $AUTOSAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Summarize our refund policy for a customer." }'

curl -N -X POST "$AUTOSAGE_URL/agents/AGENT_ID/messages/stream" \
  -H "Authorization: Bearer $AUTOSAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Summarize our refund policy for a customer." }'
The streaming endpoint returns Server-Sent Events. See Chat & streaming for how to consume the event types.

​
Review past runs

List an agent’s runs to inspect history, monitor scheduled executions, and debug behavior over time. 
curl "$AUTOSAGE_URL/agents/AGENT_ID/runs" \
  -H "Authorization: Bearer $AUTOSAGE_KEY"
Scheduled runs consume credits and, for agents that use connected apps, require a bound identity for those apps. Keep the tenant’s credit balance topped up so scheduled runs are not skipped — see Rate limits & credits.

​
Next steps

Agent in two minutes

Start with the shortest dashboard and API path.

KB prompts vs. agents

Decide which behavior belongs to the knowledge base and which belongs to the agent.

Agent lifecycle

How an agent moves from draft to deployed to running.

Configuring agents

Every configuration option in depth, with examples.

Agents API

Full endpoint reference for creating, deploying, and running agents.

Chat & streaming

Consume streamed responses in your application.