Agents - Powabase

Each agent wraps an LLM with a system prompt, tools, knowledge bases, and optional MCP servers. Agents use a ReAct loop to reason about user messages, call tools as needed, and generate streaming responses. Sessions maintain conversation history across turns.

Common Patterns

Create an agent, assign tools and knowledge bases, then use the streaming endpoint for conversations. Pass session_id to continue multi-turn conversations. For human-in-the-loop workflows, configure hooks and use the approve endpoint when approval_requested events are received.

Agent CRUD

GET /api/agents

List all agents.

response = requests.get(f"{BASE_URL}/api/agents", headers=headers)

const res = await fetch(`${BASE_URL}/api/agents`, { headers });

curl '{BASE_URL}/api/agents' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

POST /api/agents

Create a new agent.

{
  "name": "My Agent",
  "model": "gpt-4o",
  "system_prompt": "You are a helpful assistant.",
  "settings": { "temperature": 0.7 }
}

The body honors name (required), model, system_prompt, and settings (object). Top-level fields like temperature are silently dropped; anything model-tuning related must be nested in settings. model is a LiteLLM model ID passed through unchanged (e.g. gpt-4o, claude-sonnet-4-6, openrouter/<org>/<model>); see Bring your own LLM for the per-provider format and key requirements.

response = requests.post(f"{BASE_URL}/api/agents", headers=headers, json={"name": "My Agent", "model": "gpt-4o", "system_prompt": "You are helpful.", "settings": {"temperature": 0.7}})

const res = await fetch(`${BASE_URL}/api/agents`, { method: "POST", headers, body: JSON.stringify({ name: "My Agent", model: "gpt-4o", system_prompt: "You are helpful.", settings: { temperature: 0.7 } }) });

curl -X POST '{BASE_URL}/api/agents' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"name": "My Agent", "model": "gpt-4o"}'

GET /api/agents/

Get an agent by ID.

string

required

Agent ID

response = requests.get(f"{BASE_URL}/api/agents/{agent_id}", headers=headers)

const res = await fetch(`${BASE_URL}/api/agents/${agentId}`, { headers });

curl '{BASE_URL}/api/agents/{id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

PATCH /api/agents/

Update an agent’s name, model, system prompt, or settings.

string

required

Agent ID

response = requests.patch(f"{BASE_URL}/api/agents/{agent_id}", headers=headers, json={"settings": {"temperature": 0.5}})

await fetch(`${BASE_URL}/api/agents/${agentId}`, { method: "PATCH", headers, body: JSON.stringify({ settings: { temperature: 0.5 } }) });

curl -X PATCH '{BASE_URL}/api/agents/{id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"settings": {"temperature": 0.5}}'

DELETE /api/agents/

Delete an agent.

string

required

Agent ID

response = requests.delete(f"{BASE_URL}/api/agents/{agent_id}", headers=headers)

await fetch(`${BASE_URL}/api/agents/${agentId}`, { method: "DELETE", headers });

curl -X DELETE '{BASE_URL}/api/agents/{id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

Tool Assignments

POST /api/agents//tools

Assign a tool to the agent.

string

required

Agent ID

{ "tool_name": "database_query" }

response = requests.post(f"{BASE_URL}/api/agents/{agent_id}/tools", headers=headers, json={"tool_name": "database_query"})

await fetch(`${BASE_URL}/api/agents/${agentId}/tools`, { method: "POST", headers, body: JSON.stringify({ tool_name: "database_query" }) });

curl -X POST '{BASE_URL}/api/agents/{id}/tools' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"tool_name": "database_query"}'

GET /api/agents//tools

List tool assignments for the agent.

string

required

Agent ID

response = requests.get(f"{BASE_URL}/api/agents/{agent_id}/tools", headers=headers)

const res = await fetch(`${BASE_URL}/api/agents/${agentId}/tools`, { headers });

curl '{BASE_URL}/api/agents/{id}/tools' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

PATCH /api/agents//tools/

Update a tool assignment’s config_override.

string

required

Agent ID

assignment_id

string

required

Assignment ID

config_override

object

required

The full config_override object. Tool-specific shape; for database tools include schemas: { <schema_name>: [<table_name>, ...] }.

The body MUST use the key config_override. Passing config (or any other top-level key) is a silent no-op: the route returns 200 with the unchanged assignment because the handler only inspects config_override.How config_override works per tool type:

Database tools (database_query, database_write): config_override.schemas: { <schema>: [<table>, ...] } controls which tables the agent can read/write. Schemas must be a dict, schema names must match ^[a-zA-Z_][a-zA-Z0-9_]{0,63}$, system schemas (ai, auth, storage, pg_*, etc.) are rejected, and each value must be a list of valid table names.
All other builtin tools (web_search, web_scrape, http_request, code_execute, storage_read, storage_write): any key in config_override whose name matches a parameter in the tool’s input_schema is force-injected into every call’s arguments. Keys not in the schema are silently dropped (no error, no warning). For example, setting config_override: { "max_results": 3, "include_domains": ["example.com"] } on a web_search assignment locks every search the agent does to 3 results from example.com. This constrains a tool without changing what the agent is told about it: the LLM still sees the full schema, but its requested values for those keys are overridden.
Custom tools: config_override is not used. Custom-tool behavior is controlled via the Tool row’s own config (endpoint, method, headers) at create time.
MCP tools: config_override is not used. MCP-tool behavior is controlled via the AgentMcpServer row’s headers and enabled flag.

{
  "config_override": {
    "schemas": {
      "public": ["users", "orders"]
    }
  }
}

response = requests.patch(f"{BASE_URL}/api/agents/{agent_id}/tools/{assignment_id}", headers=headers, json={"config_override": {"schemas": {"public": ["users", "orders"]}}})

await fetch(`${BASE_URL}/api/agents/${agentId}/tools/${assignmentId}`, { method: "PATCH", headers, body: JSON.stringify({ config_override: { schemas: { public: ["users", "orders"] } } }) });

curl -X PATCH '{BASE_URL}/api/agents/{id}/tools/{assignment_id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"config_override": {"schemas": {"public": ["users", "orders"]}}}'

DELETE /api/agents//tools/

Remove a tool assignment from the agent.

string

required

Agent ID

assignment_id

string

required

Assignment ID

response = requests.delete(f"{BASE_URL}/api/agents/{agent_id}/tools/{assignment_id}", headers=headers)

await fetch(`${BASE_URL}/api/agents/${agentId}/tools/${assignmentId}`, { method: "DELETE", headers });

curl -X DELETE '{BASE_URL}/api/agents/{id}/tools/{assignment_id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

Knowledge Base Assignments

POST /api/agents//knowledge-bases

Link a knowledge base to the agent. Creates a dynamic search tool.

string

required

Agent ID

{ "knowledge_base_id": "kb-uuid" }

response = requests.post(f"{BASE_URL}/api/agents/{agent_id}/knowledge-bases", headers=headers, json={"knowledge_base_id": kb_id})

await fetch(`${BASE_URL}/api/agents/${agentId}/knowledge-bases`, { method: "POST", headers, body: JSON.stringify({ knowledge_base_id: kbId }) });

curl -X POST '{BASE_URL}/api/agents/{id}/knowledge-bases' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"knowledge_base_id": "kb-uuid"}'

GET /api/agents//knowledge-bases

List knowledge base assignments for the agent.

string

required

Agent ID

response = requests.get(f"{BASE_URL}/api/agents/{agent_id}/knowledge-bases", headers=headers)

const res = await fetch(`${BASE_URL}/api/agents/${agentId}/knowledge-bases`, { headers });

curl '{BASE_URL}/api/agents/{id}/knowledge-bases' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

DELETE /api/agents//knowledge-bases/

Remove a knowledge base from the agent.

string

required

Agent ID

assignment_id

string

required

Assignment ID

response = requests.delete(f"{BASE_URL}/api/agents/{agent_id}/knowledge-bases/{assignment_id}", headers=headers)

await fetch(`${BASE_URL}/api/agents/${agentId}/knowledge-bases/${assignmentId}`, { method: "DELETE", headers });

curl -X DELETE '{BASE_URL}/api/agents/{id}/knowledge-bases/{assignment_id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

MCP Servers

POST /api/agents//mcp-servers

Add an MCP server to the agent.

string

required

Agent ID

{
  "url": "https://mcp.example.com",
  "transport": "http",
  "name": "My MCP"
}

response = requests.post(f"{BASE_URL}/api/agents/{agent_id}/mcp-servers", headers=headers, json={"url": "https://mcp.example.com", "transport": "http", "name": "My MCP"})

await fetch(`${BASE_URL}/api/agents/${agentId}/mcp-servers`, { method: "POST", headers, body: JSON.stringify({ url: "https://mcp.example.com", transport: "http", name: "My MCP" }) });

curl -X POST '{BASE_URL}/api/agents/{id}/mcp-servers' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"url": "https://mcp.example.com", "transport": "http"}'

GET /api/agents//mcp-servers

List MCP servers for the agent.

string

required

Agent ID

response = requests.get(f"{BASE_URL}/api/agents/{agent_id}/mcp-servers", headers=headers)

const res = await fetch(`${BASE_URL}/api/agents/${agentId}/mcp-servers`, { headers });

curl '{BASE_URL}/api/agents/{id}/mcp-servers' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

PUT /api/agents//mcp-servers/

Update an MCP server configuration.

string

required

Agent ID

server_id

string

required

MCP Server ID

response = requests.put(f"{BASE_URL}/api/agents/{agent_id}/mcp-servers/{server_id}", headers=headers, json={"url": "https://new-url.com"})

await fetch(`${BASE_URL}/api/agents/${agentId}/mcp-servers/${serverId}`, { method: "PUT", headers, body: JSON.stringify({ url: "https://new-url.com" }) });

curl -X PUT '{BASE_URL}/api/agents/{id}/mcp-servers/{server_id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"url": "https://new-url.com"}'

DELETE /api/agents//mcp-servers/

Remove an MCP server from the agent.

string

required

Agent ID

server_id

string

required

MCP Server ID

response = requests.delete(f"{BASE_URL}/api/agents/{agent_id}/mcp-servers/{server_id}", headers=headers)

await fetch(`${BASE_URL}/api/agents/${agentId}/mcp-servers/${serverId}`, { method: "DELETE", headers });

curl -X DELETE '{BASE_URL}/api/agents/{id}/mcp-servers/{server_id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

Hooks

Intercept agent execution at lifecycle boundaries. For the full event/type semantics, the webhook request/response contract, and the streaming caveat, see Hooks & Middleware.

POST /api/agents//hooks

Add a hook to the agent.

string

required

Agent ID

event

string

required

When the hook fires. One of: OnRunStart, PreToolUse, OnDelegation, PostToolUse, PreResponse, OnRunComplete. Stored verbatim and not validated; an unrecognized value is saved but never fires.

type

string

required

What the hook does. One of: http (POST to a webhook URL), rule (local condition evaluation), approval (human-in-the-loop gate). Also stored verbatim and not validated.

config

object

required

Type-specific configuration (may be {}). For http: url (required), optional headers, timeout_seconds (default 5). For approval: optional message, timeout (default 300). For rule: a condition string or a rules array.

matcher

string

Tool name to target. Omit to match all tools (or for non-tool events).

enabled

boolean

default:"true"

Whether the hook is active.

position

integer

default:"0"

Execution order among the agent’s hooks (ascending).

Hooks are immutable; there is no update endpoint. To change a hook, DELETE it and create a new one.

# An HTTP hook that POSTs to your webhook before every tool call
response = requests.post(f"{BASE_URL}/api/agents/{agent_id}/hooks", headers=headers, json={"event": "PreToolUse", "type": "http", "config": {"url": "https://example.com/hook"}})

await fetch(`${BASE_URL}/api/agents/${agentId}/hooks`, { method: "POST", headers, body: JSON.stringify({ event: "PreToolUse", type: "http", config: { url: "https://example.com/hook" } }) });

curl -X POST '{BASE_URL}/api/agents/{id}/hooks' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"event": "PreToolUse", "type": "http", "config": {"url": "https://example.com/hook"}}'

{
  "id": "hook_...",
  "agent_id": "agent_...",
  "event": "PreToolUse",
  "matcher": null,
  "type": "http",
  "config": { "url": "https://example.com/hook" },
  "enabled": true,
  "position": 0,
  "created_at": "2026-01-01T00:00:00Z"
}

GET /api/agents//hooks

List hooks for the agent.

string

required

Agent ID

response = requests.get(f"{BASE_URL}/api/agents/{agent_id}/hooks", headers=headers)

const res = await fetch(`${BASE_URL}/api/agents/${agentId}/hooks`, { headers });

curl '{BASE_URL}/api/agents/{id}/hooks' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

DELETE /api/agents//hooks/

Remove a hook from the agent.

string

required

Agent ID

hook_id

string

required

Hook ID

response = requests.delete(f"{BASE_URL}/api/agents/{agent_id}/hooks/{hook_id}", headers=headers)

await fetch(`${BASE_URL}/api/agents/${agentId}/hooks/${hookId}`, { method: "DELETE", headers });

curl -X DELETE '{BASE_URL}/api/agents/{id}/hooks/{hook_id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

Execution

GET /api/agents//sessions

List chat sessions for the agent.

string

required

Agent ID

response = requests.get(f"{BASE_URL}/api/agents/{agent_id}/sessions", headers=headers)

const res = await fetch(`${BASE_URL}/api/agents/${agentId}/sessions`, { headers });

curl '{BASE_URL}/api/agents/{id}/sessions' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

POST /api/agents//run

Run agent synchronously, returning the full response as JSON. No streaming, no tools, no ReAct loop: a single LLM call against the conversation context. Useful for question-answering. If you need tool use, use /run/stream. The endpoint accepts the same context-selection surface as /run/stream: you can attach ad-hoc retrieval (knowledge_bases), a pre-built context (context_handler_id), a raw context string (context_override), or by-reference items (context_items). Only one context source may be provided per request; sending more than one returns 400.

string

required

Agent ID

{
  "message": "Hello",
  "session_id": "optional-session-uuid",
  "knowledge_bases": [{ "id": "kb-uuid", "top_k": 5 }],
  "max_context_tokens": 8000,
  "citations_enabled": false
}

Body field	Type	Notes
`message`	string (required)	User input
`session_id`	string	Reuse a session for multi-turn. Omit to start a fresh session; `session_id` is returned.
`knowledge_bases`	array	Ad-hoc retrieval: `[{ id, top_k?, similarity_threshold?, filter_metadata?, retrieval_method? }]`
`context_handler_id`	string	Use a pre-built context handler (see Context Handlers)
`context_override`	string	Raw context string injected verbatim; skips retrieval
`context_items`	array	By-reference items: `[{ id, ... }]` or by-value items with `text`
`max_context_tokens`	int	Truncate retrieved context to this token budget (default from agent settings or platform default)
`citations_enabled`	bool	Append a citation instruction and parse `[1]`-style refs from the response (default `false`)
`temperature`	float	Per-run override; falls back to agent setting
`response_format`	object	LiteLLM-compatible JSON-schema for structured output

response = requests.post(f"{BASE_URL}/api/agents/{agent_id}/run", headers=headers, json={"message": "Hello"})

const res = await fetch(`${BASE_URL}/api/agents/${agentId}/run`, { method: "POST", headers, body: JSON.stringify({ message: "Hello" }) });

curl -X POST '{BASE_URL}/api/agents/{id}/run' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"message": "Hello"}'

POST /api/agents//run/stream

Run agent with streaming SSE. Supports tools, the ReAct loop, and multi-turn via session_id. SSE event types include start, chunk, tool_call, tool_result, reasoning, reasoning_summary, and complete; the reasoning events surface the model’s internal thought stream when reasoning is enabled. Set reasoning_requested=true to request reasoning output for this run. The streaming endpoint accepts the same context-selection surface as /run above (knowledge_bases / context_handler_id / context_override / context_items, mutually exclusive), plus all the same max_context_tokens, citations_enabled, temperature, and response_format fields. See Streaming for the full SSE event catalog.

string

required

Agent ID

{
  "message": "Hello",
  "session_id": "optional-session-uuid",
  "reasoning_requested": false,
  "knowledge_bases": [{ "id": "kb-uuid", "top_k": 5 }]
}

response = requests.post(
    f"{BASE_URL}/api/agents/{agent_id}/run/stream",
    headers=headers,
    json={"message": "Hello", "reasoning_requested": True},
    stream=True,
)
for line in response.iter_lines():
    if line and line.decode().startswith("data: "):
        event = json.loads(line.decode()[6:])
        print(event)

const response = await fetch(`${BASE_URL}/api/agents/${agentId}/run/stream`, {
  method: "POST", headers,
  body: JSON.stringify({ message: "Hello", reasoning_requested: true }),
});
// Parse SSE events: start, chunk, tool_call, tool_result, reasoning, complete

curl -N -X POST '{BASE_URL}/api/agents/{id}/run/stream' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"message": "Hello", "reasoning_requested": true}'

GET /api/agents/runs/

Fetch a single agent run by run_id, independent of session context. Returns: id, run_id, session_id, parent_orchestration_run_id, parent_workflow_execution_id, status, input_messages, output_messages, content, usage, retrieved_context, error, started_at, completed_at, steps, events, tool_calls, reasoning_steps, and created_at. The parent fields are null for top-level runs; session_id is null for delegated or workflow-block runs. For runs that belong to a session, ownership is enforced: the caller must own the session (or be using a service-role key). To avoid leaking existence, ownership failures are returned as 404, not 403.

run_id

string

required

Run ID

response = requests.get(f"{BASE_URL}/api/agents/runs/{run_id}", headers=headers)

const res = await fetch(`${BASE_URL}/api/agents/runs/${runId}`, { headers });

curl '{BASE_URL}/api/agents/runs/{run_id}' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

POST /api/agents/runs//approve

Approve or deny a pending tool call (human-in-the-loop).

run_id

string

required

Run ID

{ "approved": true }

response = requests.post(f"{BASE_URL}/api/agents/runs/{run_id}/approve", headers=headers, json={"approved": True})

await fetch(`${BASE_URL}/api/agents/runs/${runId}/approve`, { method: "POST", headers, body: JSON.stringify({ approved: true }) });

curl -X POST '{BASE_URL}/api/agents/runs/{run_id}/approve' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"approved": true}'

Error Responses

Agent routes return {"error": "<message>"}.

Status	Description
400	Missing or invalid required field (e.g. `name`, `tool_type`/`tool_name`, `knowledge_base_id`, MCP server `name`/`url`, hook `event`/`type`/`config`)
400	Invalid `config_override.schemas` on tool PATCH (e.g. not a dict, contains a system schema, or has invalid table names)
404	No agent, tool/KB/MCP/hook assignment, or run exists with the given ID
404	`/run` or `/run/stream`: the supplied `session_id` is not owned by the caller (returned as 404 to avoid leaking existence)
409	Knowledge base already assigned to this agent
409	An MCP server with this name already exists for this agent

​Common Patterns

​Agent CRUD

​GET /api/agents

​POST /api/agents

​GET /api/agents/

​PATCH /api/agents/

​DELETE /api/agents/

​Tool Assignments

​POST /api/agents//tools

​GET /api/agents//tools

​PATCH /api/agents//tools/

​DELETE /api/agents//tools/

​Knowledge Base Assignments

​POST /api/agents//knowledge-bases

​GET /api/agents//knowledge-bases

​DELETE /api/agents//knowledge-bases/

​MCP Servers

​POST /api/agents//mcp-servers

​GET /api/agents//mcp-servers

​PUT /api/agents//mcp-servers/

​DELETE /api/agents//mcp-servers/

​Hooks

​POST /api/agents//hooks

​GET /api/agents//hooks

​DELETE /api/agents//hooks/

​Execution

​GET /api/agents//sessions

​POST /api/agents//run

​POST /api/agents//run/stream

​GET /api/agents/runs/

​POST /api/agents/runs//approve

​Error Responses

Common Patterns

Agent CRUD

GET /api/agents

POST /api/agents

GET /api/agents/

PATCH /api/agents/

DELETE /api/agents/

Tool Assignments

POST /api/agents//tools

GET /api/agents//tools

PATCH /api/agents//tools/

DELETE /api/agents//tools/

Knowledge Base Assignments

POST /api/agents//knowledge-bases

GET /api/agents//knowledge-bases

DELETE /api/agents//knowledge-bases/

MCP Servers

POST /api/agents//mcp-servers

GET /api/agents//mcp-servers

PUT /api/agents//mcp-servers/

DELETE /api/agents//mcp-servers/

Hooks

POST /api/agents//hooks

GET /api/agents//hooks

DELETE /api/agents//hooks/

Execution

GET /api/agents//sessions

POST /api/agents//run

POST /api/agents//run/stream

GET /api/agents/runs/

POST /api/agents/runs//approve

Error Responses