Overview

Agents in Polos use LLMs to autonomously reason about tasks and decide which actions to take. This guide covers the fundamentals of creating and running agents.

Defining an agent

Create an agent by specifying a model provider, system prompt, and optional tools:

from polos import Agent, tool, WorkflowContext
from pydantic import BaseModel

class WeatherInput(BaseModel):
    city: str

class WeatherOutput(BaseModel):
    temperature: float
    condition: str
    city: str

@tool(description="Get current weather for a city")
async def get_weather(ctx: WorkflowContext, input: WeatherInput) -> WeatherOutput:
    # Call weather API
    data = await weather_api.get(input.city)
    return WeatherOutput(
        city=input.city,
        temperature=data.temp,
        condition=data.conditions
    )

weather_agent = Agent(
    id="weather-agent",
    provider="openai",
    model="gpt-4o",
    system_prompt="You are a helpful weather assistant. Use the get_weather tool to answer questions about weather.",
    tools=[get_weather]
)

import { defineAgent, defineTool, WorkflowContext } from "@polos/sdk";
import { openai } from "@ai-sdk/openai";
import { z } from "zod";

const WeatherInput = z.object({
  city: z.string(),
});

const WeatherOutput = z.object({
  temperature: z.number(),
  condition: z.string(),
  city: z.string(),
});

const getWeather = defineTool(
  {
    id: "get-weather",
    description: "Get current weather for a city",
    inputSchema: WeatherInput,
    outputSchema: WeatherOutput,
  },
  async (ctx: WorkflowContext, input) => {
    // Call weather API
    const data = await weatherApi.get(input.city);
    return {
      city: input.city,
      temperature: data.temp,
      condition: data.conditions,
    };
  }
);

const weatherAgent = defineAgent({
  id: "weather-agent",
  model: openai("gpt-4o"),
  systemPrompt:
    "You are a helpful weather assistant. Use the get_weather tool to answer questions about weather.",
  tools: [getWeather],
});

Agent configuration

Required parameters:

id - Unique identifier for the agent
provider - LLM provider (see supported providers below)
model - Model name (e.g., “gpt-4o”, “claude-sonnet-4”)

Optional parameters:

system_prompt - Instructions that guide the agent’s behavior
tools - List of tools the agent can call
output_schema - Pydantic model for structured outputs
stop_conditions - Conditions that terminate agent execution

Supported providers

openai - OpenAI (GPT-5, GPT-5-mini, GPT-4o, etc.)
anthropic - Anthropic (Claude Sonnet, Claude Opus, etc.)
gemini - Google Gemini
groq - Groq
fireworks - Fireworks AI
together - Together AI
azure - Azure OpenAI

Running agents

Synchronous execution with `agent.run()`

Use agent.run() for complete execution:

import asyncio
from polos import PolosClient

async def main():
    client = PolosClient()
    response = await weather_agent.run(
        client,
        "What's the weather like in New York and London? Compare them."
    )

    print(response.result)
    # Agent automatically:
    # 1. Calls get_weather("New York")
    # 2. Calls get_weather("London")
    # 3. Generates comparison
    # 4. Returns final answer

if __name__ == "__main__":
    asyncio.run(main())

import { PolosClient } from "@polos/sdk";

async function main() {
  const client = PolosClient.fromEnv();
  const response = await weatherAgent.run(
    client,
    "What's the weather like in New York and London? Compare them."
  );

  console.log(response.result);
  // Agent automatically:
  // 1. Calls getWeather("New York")
  // 2. Calls getWeather("London")
  // 3. Generates comparison
  // 4. Returns final answer
}

main();

How it works:

Agent receives your message
LLM analyzes the request and decides if tools are needed
If tools are needed, agent executes them. If multiple tool calls are needed, they are executed in parallel.
Agent feeds tool results back to the LLM
Process repeats until the agent has a final answer or hits a stop condition
Returns the complete response

Provider-specific parameters

You can pass any keyword argument supported by your provider:

# Anthropic extended thinking
response = await anthropic_agent.run(
    client,
    "What's the weather in New York? How did it impact my day?",
    thinking={
        "type": "enabled",
        "budget_tokens": 4000
    }
)

# OpenAI reasoning
response = await openai_agent.run(
    client,
    "Analyze the weather patterns",
    reasoning_effort="high"  # OpenAI o1 models
)

# Temperature and other common parameters
response = await weather_agent.run(
    client,
    "What's the weather?",
    temperature=0.7,
    max_tokens=1000,
    top_p=0.9
)

// Anthropic extended thinking
const response1 = await anthropicAgent.run(
  client,
  "What's the weather in New York? How did it impact my day?",
  {
    thinking: {
      type: "enabled",
      budget_tokens: 4000,
    },
  }
);

// OpenAI reasoning
const response2 = await openaiAgent.run(
  client,
  "Analyze the weather patterns",
  {
    reasoning_effort: "high", // OpenAI o1 models
  }
);

// Temperature and other common parameters
const response3 = await weatherAgent.run(
  client,
  "What's the weather?",
  {
    temperature: 0.7,
    max_tokens: 1000,
    top_p: 0.9,
  }
);

These parameters are passed directly to the underlying provider API.

Streaming with `agent.stream()`

Stream responses for real-time feedback:

async def main():
    client = PolosClient()
    stream = await weather_agent.stream(
        client, "What's the weather in Tokyo?"
    )

    # Stream text chunks as they arrive
    async for chunk in stream.text_chunks:
        print(chunk, end="", flush=True)

    print("\n")

if __name__ == "__main__":
    asyncio.run(main())

import { PolosClient } from "@polos/sdk";

async function main() {
  const client = PolosClient.fromEnv();
  const stream = await weatherAgent.stream(
    client,
    "What's the weather in Tokyo?"
  );

  // Stream text chunks as they arrive
  for await (const chunk of stream.textChunks) {
    process.stdout.write(chunk);
  }

  console.log("\n");
}

main();

Stream features:

Real-time token streaming
Access to intermediate tool calls
Progress tracking

You can also pass provider-specific parameters to agent.stream():

stream = await weather_agent.stream(
    client,
    "Compare weather across multiple cities",
    temperature=0.8,
    max_tokens=2000
)

const stream = await weatherAgent.stream(
  client,
  "Compare weather across multiple cities",
  {
    temperature: 0.8,
    max_tokens: 2000,
  }
);

See Streaming for advanced streaming patterns.

Agent responses

Both agent.run() and agent.stream() return response objects with useful information:

response = await weather_agent.run("What's the weather in SF?")

# Access the final text result
print(response.result)

# View tool results
for tool_result in response.tool_results:
    print(f"Tool: {tool_result.tool_name}")
    print(f"Input: {tool_result.result}")

# Check token usage
print(f"Total tokens: {response.usage.total_tokens}")
print(f"Input tokens: {response.usage.input_tokens}")
print(f"Output tokens: {response.usage.output_tokens}")

const response = await weatherAgent.run("What's the weather in SF?");

// Access the final text result
console.log(response.result);

// View tool results
for (const toolResult of response.toolResults) {
  console.log(`Tool: ${toolResult.toolName}`);
  console.log(`Input: ${toolResult.result}`);
}

// Check token usage
console.log(`Total tokens: ${response.usage.totalTokens}`);
console.log(`Input tokens: ${response.usage.inputTokens}`);
console.log(`Output tokens: ${response.usage.outputTokens}`);

Triggering agents from Slack

You can trigger agents directly from Slack by @mentioning your bot. The agent’s output streams back to the originating Slack thread.

@polos @sales-agent What's the latest on Acme?

@sales-agent is the ID of the agent you want to trigger. The bot routes the message to the right agent and streams the response back to the same thread. To set this up, create a Slack app, configure event subscriptions, and register the app with your orchestrator. See Slack Integration for the full setup guide.

Sandbox tools

Give agents the ability to write code, run shell commands, and explore a codebase inside a controlled environment. A single call to sandboxTools() creates six tools (exec, read, write, edit, glob, grep) that share an execution environment.

from polos import Agent, sandbox_tools, SandboxToolsConfig, DockerEnvironmentConfig

tools = sandbox_tools(SandboxToolsConfig(
    env="docker",
    scope="session",
    docker=DockerEnvironmentConfig(
        image="node:20-slim",
    ),
))

coding_agent = Agent(
    id="coding_agent",
    provider="anthropic",
    model="claude-opus-4-5",
    system_prompt="You are a coding assistant.",
    tools=tools,
)

import { defineAgent, sandboxTools } from '@polos/sdk';
import { anthropic } from '@ai-sdk/anthropic';

const tools = sandboxTools({
  env: 'docker',
  scope: 'session',
  docker: {
    image: 'node:20-slim',
  },
});

const codingAgent = defineAgent({
  id: 'coding_agent',
  model: anthropic('claude-opus-4-5'),
  systemPrompt: 'You are a coding assistant.',
  tools: [...tools],
});

Polos supports three execution environments:

Environment	Isolation	Best for
`docker`	Container	Production, untrusted code
`local`	None (host machine)	Development, trusted agents
`e2b` (coming soon)	Cloud sandbox	Cloud-native deployments

The exec tool supports security modes to control which commands run without approval: allow-always (default for Docker), allowlist (pattern-based), and approval-always (default for local). See Sandbox for the full configuration reference.

Agent durability

Agents in Polos are durable - they survive failures and resume from the last completed step. What gets persisted:

Tool call inputs and outputs
LLM reasoning steps
Conversation history
Agent state

Example recovery scenario:

# Agent execution starts
response = await weather_agent.run(client, "Compare weather in 5 cities")

# Agent calls get_weather("New York") ✓ - cached
# Agent calls get_weather("London") ✓ - cached
# Worker crashes ❌

# On retry:
# Agent resumes from last completed step
# get_weather("New York") - returns cached result (no API call)
# get_weather("London") - returns cached result (no API call)
# Continues with remaining cities

// Agent execution starts
const response = await weatherAgent.run(client, "Compare weather in 5 cities");

// Agent calls getWeather("New York") ✓ - cached
// Agent calls getWeather("London") ✓ - cached
// Worker crashes ❌

// On retry:
// Agent resumes from last completed step
// getWeather("New York") - returns cached result (no API call)
// getWeather("London") - returns cached result (no API call)
// Continues with remaining cities

Benefits:

No duplicate tool calls
No wasted API tokens
No lost progress

See Durable Execution for how this works under the hood.

Using agents in workflows

Agents are workflows, so you can compose them with other workflow steps:

from polos import workflow, WorkflowContext

@workflow
async def customer_support_workflow(ctx: WorkflowContext, input: CustomerSupportInput):
    # Run agent to handle customer query
    agent_response = await ctx.step.agent_invoke_and_wait(
        "weather_agent",
        weather_agent.with_input(input.question)
    )

    # Log the interaction
    await ctx.step.run("log", log_interaction, agent_response)

    # Send follow-up email
    await ctx.step.run(
        "send_email",
        send_email,
        to=input.customer_email,
        body=agent_response.result
    )

    return agent_response

import { defineWorkflow, WorkflowContext } from "@polos/sdk";

const customerSupportWorkflow = defineWorkflow(
  async (ctx: WorkflowContext, input: CustomerSupportInput) => {
    // Run agent to handle customer query
    const agentResponse = await ctx.step.agentInvokeAndWait(
      "weather_agent",
      weatherAgent.withInput(input.question)
    );

    // Log the interaction
    await ctx.step.run("log", logInteraction, agentResponse);

    // Send follow-up email
    await ctx.step.run(
      "send_email",
      sendEmail,
      { to: input.customerEmail, body: agentResponse.result }
    );

    return agentResponse;
  }
);

This combines agent autonomy with workflow orchestration for complex multi-step processes.

Next steps

Core features:

Tools - Give agents the ability to take actions
Sandbox - Isolated execution environments for code and shell commands
Streaming - Real-time response streaming
Structured Outputs - Extract structured data
Slack Integration - Trigger agents from Slack

Advanced patterns:

Stop Conditions - Control when agents stop
Conversation Memory - Multi-turn conversations
Human-in-the-Loop - Approval workflows
Guardrails - Safety and compliance
Lifecycle Hooks - Customize agent behavior

Introduction

Getting Started

Fundamentals

Agents

Workflows

Observability

Guides and Examples

Community

Defining an agent

Agent configuration

Supported providers

Running agents

Synchronous execution with `agent.run()`

Provider-specific parameters

Streaming with `agent.stream()`

Agent responses

Triggering agents from Slack

Sandbox tools

Agent durability

Using agents in workflows

Next steps

​Defining an agent

​Agent configuration

​Supported providers

​Running agents

​Synchronous execution with agent.run()

​Provider-specific parameters

​Streaming with agent.stream()

​Agent responses

​Triggering agents from Slack

​Sandbox tools

​Agent durability

​Using agents in workflows

​Next steps

Defining an agent

Agent configuration

Supported providers

Running agents

Synchronous execution with `agent.run()`

Provider-specific parameters

Streaming with `agent.stream()`

Agent responses

Triggering agents from Slack

Sandbox tools

Agent durability

Using agents in workflows

Next steps