Skip to content

Agents Guide

Agents are systems that independently accomplish tasks on your behalf. Unlike simple chatbots, agents control workflow execution and make decisions autonomously.

What Makes an Agent

An agent has three core components:

  1. Model - The LLM powering reasoning and decisions
  2. Tools - External functions the agent can call
  3. Instructions - Guidelines defining behavior
from pauhu import Agent

support_agent = Agent(
    name="Customer Support",
    instructions="Help customers resolve their issues efficiently.",
    tools=[search_orders, process_refund, escalate_to_human],
)

When to Build an Agent

Build an agent when your workflow has:

  • Complex decision-making - Nuanced judgment, exceptions, context-sensitive choices
  • Difficult-to-maintain rules - Systems with extensive, brittle rulesets
  • Unstructured data - Natural language, documents, conversational input

If a simple rules engine works, use that instead.

Agent Types

Single-Agent Systems

One agent with multiple tools handles the entire workflow.

agent = Agent(
    name="Research Assistant",
    instructions="Search for information and summarize findings.",
    tools=[web_search, summarize, save_results],
)

Multi-Agent Systems

Multiple specialized agents coordinate on complex workflows.

Manager Pattern - Central agent delegates to specialists:

manager = Agent(
    name="Manager",
    tools=[
        sales_agent.as_tool(),
        support_agent.as_tool(),
        billing_agent.as_tool(),
    ],
)

Decentralized Pattern - Agents hand off to each other:

triage_agent = Agent(
    name="Triage",
    handoffs=[sales_agent, support_agent, billing_agent],
)

Guardrails

Guardrails protect against misuse and errors:

  • Relevance classifier - Keeps responses on-topic
  • Safety classifier - Detects jailbreak attempts
  • PII filter - Prevents data leaks
  • Tool safeguards - Risk-rate each tool
@input_guardrail
async def safety_check(ctx, agent, input):
    # Check for unsafe content
    result = await safety_classifier(input)
    return GuardrailOutput(tripwire_triggered=result.is_unsafe)

agent = Agent(
    name="Support",
    input_guardrails=[safety_check],
)

Human Intervention

Always plan for human handoff when:

  • Agent exceeds failure thresholds
  • High-risk actions need approval
  • User requests human assistance

Next Steps