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

# Build an agent

> Create, configure, deploy, and run a knowledge-grounded agent end to end with the API.

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](/developers/quickstart) first — it provisions a tenant, a knowledge base, and an uploaded document in a few minutes.

```bash theme={null}
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.

<ParamField body="tenant_id" type="string" required>
  The tenant the agent belongs to.
</ParamField>

<ParamField body="name" type="string" required>
  A human-readable name for the agent.
</ParamField>

<ParamField body="selected_knowledge_base_id" type="string" required>
  The knowledge base the agent draws grounded answers from. This is **fixed at creation** — see the note below.
</ParamField>

<ParamField body="model_id" type="string" required>
  The model that powers the agent's reasoning and responses.
</ParamField>

<ParamField body="goal" type="string" required>
  A short statement of what the agent is for.
</ParamField>

<ParamField body="instructions" type="string" required>
  Detailed behavior guidance — tone, format, boundaries, and how to handle edge cases.
</ParamField>

<ParamField body="enabled_integration_slugs" type="string[]">
  Connected apps the agent may use (for example a CRM or calendar). Each app must be authenticated first — see below.
</ParamField>

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

<ParamField body="custom_tools" type="object[]">
  Custom tool definitions the agent can call.
</ParamField>

<ParamField body="callable_agents" type="object[]">
  Other agents this agent may delegate to, each identified by `agent_id`.
</ParamField>

<ParamField body="schedule" type="object">
  An optional schedule to run the agent automatically. Schedules run in UTC.
</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",
    "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.

<Note>
  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.
</Note>

<Warning>
  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`.
</Warning>

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

```bash theme={null}
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.

<CodeGroup>
  ```bash Non-streaming theme={null}
  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." }'
  ```

  ```bash Streaming 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": "Summarize our refund policy for a customer." }'
  ```
</CodeGroup>

The streaming endpoint returns Server-Sent Events. See [Chat & streaming](/developers/guides/chat-and-stream) 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.

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

<Info>
  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](/developers/rate-limits).
</Info>

## Next steps

<CardGroup cols={2}>
  <Card title="Agent in two minutes" icon="stopwatch" href="/guides/agent-in-two-minutes">
    Start with the shortest dashboard and API path.
  </Card>

  <Card title="KB prompts vs. agents" icon="scale-balanced" href="/guides/kb-prompts-vs-agents">
    Decide which behavior belongs to the knowledge base and which belongs to the agent.
  </Card>

  <Card title="Agent lifecycle" icon="arrows-spin" href="/developers/lifecycles/agent-lifecycle">
    How an agent moves from draft to deployed to running.
  </Card>

  <Card title="Configuring agents" icon="sliders" href="/agents/configuring">
    Every configuration option in depth, with examples.
  </Card>

  <Card title="Agents API" icon="code" href="/developers/api/agents">
    Full endpoint reference for creating, deploying, and running agents.
  </Card>

  <Card title="Chat & streaming" icon="bolt" href="/developers/guides/chat-and-stream">
    Consume streamed responses in your application.
  </Card>
</CardGroup>