adding-capabilities

Adding Capabilities to Agents

Overview

Agent2 capabilities are opt-in. Start with a simple agent (schema + tools + prompt), then add capabilities as your use case requires them.

When to Activate

• User says "add resume", "add approval", "add knowledge", "add provider policy"
• Agent needs multi-turn conversations
• Agent needs human-in-the-loop before executing side effects
• Agent needs cost-optimized provider routing
• Agent needs per-request tool filtering

Capability Quick Reference

Capability	When You Need It	What It Adds
Pause/Resume	Multi-turn workflows, clarification loops	message_history serialization
Approval Workflow	Human must approve before side effects	pending_actions + execute endpoint
Provider Policy	Cost control, prompt cache optimization	provider_order in config
Tool Scoping	Per-tenant or per-request tool filtering	Tool policy in before_run()
Knowledge Search	Agent needs domain documents	R2R + Knowledge MCP via toolsets=

Pause/Resume

Add when: Agent needs to ask a question and wait for a human to answer before continuing.

1. Accept history in before_run

def before_run(input_data: dict) -> dict:
    if input_data.get("message_history"):
        input_data["_instructions"] = (
            "Continue the conversation. Read the human's response and proceed."
        )
    return input_data

2. Persist history in after_run

The framework auto-serializes _message_history into the response. Your host product stores it wherever it wants (Redis, Postgres, Convex, etc.) and sends it back on the next call.

3. Advertise in config

capabilities:
  - resume

Approval Workflow

Add when: Agent proposes side effects (send email, update records, make payments) that need human sign-off.

1. Return pending_actions from agent output or mock_result

def mock_result(input_data: dict) -> dict:
    return {
        "status": "needs_approval",
        "pending_actions": [
            {
                "action": "send_email",
                "params": {"to": "[email protected]", "body": "..."},
                "description": "Send follow-up email to the client.",
            }
        ],
    }