---
title: "Run an Agent"
method: POST
path: "/"
---

# Run an Agent

`POST /`

Run an agent on a task or message.  
A new session can be created by omitting the `session` query parameter, or an existing
session can be continued by specifying the session ID in the `session` query parameter.  
The request body includes the message, optional system prompt, mode, MCP server configuration,
optional rules and whether the response should be streamed.  
The response is a streaming response and returns a sequence of events representing the
agent’s thoughts and responses.

## Query parameters

- `session` string

## Request body

- object
  - `message` string, required — The task or message to run the agent with.
  - `mode` 'flash' | 'fast' | 'max' — The agent mode. Allowed values are `flash`, `fast` or `max`. Defaults to `fast` if not supplied.
  - `system` string — A system prompt to provide system information to the agent.
  - `mcp_servers` object[] — A list of MCP server configurations. Each object must include a `serverName` and `serverUrl`.
    - `serverName` string, required — Name of the MCP server.
    - `serverUrl` string, uri, required — URL of the MCP server.
  - `datastores` object[] — A set of datastores for the agent to utilize. Each object must include a `id` and `name`.
    - `id` string, required — The ID of the datastore.
    - `name` string, required — The name of the datastore.
  - `workflows` object[] — A set of declarative workflows for the agent to execute. Each workflow is a DAG (Directed Acyclic Graph) of steps that the agent interprets and executes dynamically.
    - `id` string, required — Unique identifier for the workflow.
    - `name` string, required — Name of the workflow.
    - `description` string, required — What the workflow accomplishes.
    - `steps` object[], required — Array of step objects.
      - `id` string, required — Unique identifier for the step.
      - `name` string, required — Name of the step.
      - `description` string, required — What the step should accomplish.
      - `depends_on` string[], required — Array of step IDs that must complete before this step runs.
      - `optional` boolean — Whether the step can be skipped if it fails.
      - `retry_policy` object — Retry configuration for the step.
        - `max_attempts` integer
        - `backoff` string
      - `output_schema` object — JSON schema for expected output validation.
  - `queries` object[] — A set of custom actions based on datastore (database) queries. Allows you to quickly define actions that the agent can use to query your datastores.
    - `name` string, required — Name of the query action.
    - `description` string, required — Description of what the query does.
    - `query` string, required — The SQL query to execute.
  - `rules` string[] — A list of constraints that the agent must follow.
  - `agents` object[] — A set of agent configurations that enables the agent to transfer conversations to other specialized agents. When provided, the main agent will have access to seamless handoffs between agents based on the conversation context.
    - `name` string, required — The name of the agent to transfer to
    - `description` string, required — Description of what this agent handles
  - `background` boolean — Whether to run the agent asynchronously on the server. When set to true, use callback parameter to receive events.
  - `callback` object — A callback endpoint configuration to send agent message events back to. Use with background true.
    - `url` string, uri, required — The webhook URL to send events to.
    - `headers` object — Optional headers to include in the callback request.
  - `streaming_tokens` boolean — Whether to stream the agent messages token by token.
  - `final_output` object — Configuration for an extra final output event that processes the entire agent message thread and produces a structured output based on the provided JSON schema.
    - `name` string, required — Name for the final output.
    - `strict` boolean — Whether to enforce strict schema validation.
    - `schema` object, required — JSON schema defining the structure of the final output.

## Response `200`

Streamed agent response.  Clients should consume the response as a text/event‑stream.

## Changes

- **2025-11-06** `c12be3e0fb0d` — 1 info
  - added the new optional request property `agents`
- **2025-10-11** `461274f650ec` — 5 info
  - added the new optional request property `background`
  - added the new optional request property `callback`
  - added the new optional request property `final_output`
  - added the new optional request property `queries`
  - …1 more
- **2025-10-03** `b248631a2800` — 1 info
  - added the new optional request property `datastores`
- **2025-10-03** `ef0ae966d97c` — 2 warning, 2 info
  - removed the request property `mcpServers`
  - removed the request property `streaming`
  - added the new optional request property `mcp_servers`
  - added the new optional request property `streaming_tokens`

[Change history](https://skmtc.dev/agentbasehq/apis/agentbase-agents-api/changes/post.md)

---

[API](https://skmtc.dev/agentbasehq/apis/agentbase-agents-api.md) · [All operations](https://skmtc.dev/agentbasehq/apis/agentbase-agents-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/agentbasehq/agentbase-agents-api/revisions/c12be3e0fb0d/schema)