Build an Agent - Powabase

Agents are the conversational interface to your AI features. This guide creates an agent, gives it a tool and a knowledge base, then runs a streaming multi-turn conversation against it.

Prerequisites:

Authentication configured (see Authentication guide)
Optional: A knowledge base for RAG (see Create a Knowledge Base guide)

Create the agent

Define the agent with a name, LLM model, and system prompt that describes its behavior.Endpoint: POST /api/agents

model is a LiteLLM model ID. Bare IDs (gpt-4o, claude-sonnet-4-6) route to OpenAI/Anthropic; other providers are prefixed (gemini/..., openrouter/...). The field is not limited to the Studio model picker, but a provider you haven’t registered a key for (and that isn’t AI-on-us) returns 402 provider_key_decrypt_failed. Bring your own LLM covers the formats and an OpenRouter/DeepSeek example.

response = requests.post(
    f"{BASE_URL}/api/agents",
    headers=headers,
    json={
        "name": "Support Bot",
        "model": "gpt-4o",
        "system_prompt": "You are a helpful support assistant. Answer questions using the knowledge base when available.",
        "settings": {"temperature": 0.7},
    },
)
agent = response.json()
agent_id = agent["id"]
print(f"Agent created: {agent_id}")

const response = await fetch(`${BASE_URL}/api/agents`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    name: "Support Bot",
    model: "gpt-4o",
    system_prompt: "You are a helpful support assistant. Answer questions using the knowledge base when available.",
    settings: { temperature: 0.7 },
  }),
});
const agent = await response.json();
console.log("Agent created:", agent.id);

curl -X POST '{BASE_URL}/api/agents' \
  -H "apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Bot",
    "model": "gpt-4o",
    "system_prompt": "You are a helpful support assistant.",
    "settings": {"temperature": 0.7}
  }'

Assign a builtin tool

Enable the agent to use builtin tools like database_query, http_request, or code_execute.Endpoint: POST /api/agents/{id}/tools

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

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/{agent_id}/tools' \
  -H "apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"tool_name": "database_query"}'

Link a knowledge base

Assign a knowledge base and the agent automatically gets a search tool for it. During a conversation it can search the KB to ground its responses.Endpoint: POST /api/agents/{id}/knowledge-bases

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

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/{agent_id}/knowledge-bases' \
  -H "apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"knowledge_base_id": "{kb_id}"}'

Chat with the agent (streaming)

Send a message and receive a Server-Sent Events (SSE) stream. Events include tool calls, tool results, and the final response.Endpoint: POST /api/agents/{id}/run/stream

SSE events: start, chunk, step_started, tool_call, tool_result, step_completed, approval_requested, complete, error.

response = requests.post(
    f"{BASE_URL}/api/agents/{agent_id}/run/stream",
    headers=headers,
    json={"message": "What does the product documentation say about getting started?"},
    stream=True,
)

session_id = None
for line in response.iter_lines():
    if not line:
        continue
    text = line.decode("utf-8")
    if text.startswith("data: "):
        import json
        event = json.loads(text[6:])
        if event["event"] == "start":
            session_id = event["session_id"]
        elif event["event"] == "chunk":
            print(event["content"], end="")
        elif event["event"] == "tool_call":
            print(f"\n[Tool: {event['tool_name']}]")
        elif event["event"] == "complete":
            print(f"\n\nDone. Session: {session_id}")

const response = await fetch(`${BASE_URL}/api/agents/${agentId}/run/stream`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    message: "What does the product documentation say about getting started?",
  }),
});

const reader = response.body!.getReader();
const decoder = new TextDecoder();
let sessionId: string | null = null;

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const text = decoder.decode(value);
  for (const line of text.split("\n")) {
    if (line.startsWith("data: ")) {
      const event = JSON.parse(line.slice(6));
      if (event.event === "start") sessionId = event.session_id;
      if (event.event === "chunk") process.stdout.write(event.content);
      if (event.event === "tool_call") console.log(`\n[Tool: ${event.tool_name}]`);
      if (event.event === "complete") console.log(`\nDone. Session: ${sessionId}`);
    }
  }
}

curl -N -X POST '{BASE_URL}/api/agents/{agent_id}/run/stream' \
  -H "apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"message": "What does the product documentation say about getting started?"}'

Continue the conversation

Pass the session_id from the previous run to continue the multi-turn conversation. The agent retains full message history within the session.Endpoint: POST /api/agents/{id}/run/stream

response = requests.post(
    f"{BASE_URL}/api/agents/{agent_id}/run/stream",
    headers=headers,
    json={
        "message": "Can you summarize that in bullet points?",
        "session_id": session_id,
    },
    stream=True,
)

for line in response.iter_lines():
    if not line:
        continue
    text = line.decode("utf-8")
    if text.startswith("data: "):
        event = json.loads(text[6:])
        if event["event"] == "chunk":
            print(event["content"], end="")

const response = await fetch(`${BASE_URL}/api/agents/${agentId}/run/stream`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    message: "Can you summarize that in bullet points?",
    session_id: sessionId,
  }),
});
// ... parse SSE stream same as above

curl -N -X POST '{BASE_URL}/api/agents/{agent_id}/run/stream' \
  -H "apikey: {API_KEY}" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"message": "Can you summarize that in bullet points?", "session_id": "{session_id}"}'

What’s Next

Streaming Responses

Deep dive into SSE event handling.

Advanced Agent Config

Add MCP servers, hooks, and approval flows.

Agents & Tools

Understand the ReAct loop and tool system.

​What’s Next

Streaming Responses

Advanced Agent Config

Agents & Tools

What’s Next