Skip to main content

Agent

The Agent class is the primary interface for interacting with AgentFlow agents.

Retrieving agents

import agentflow as af

# By name
agent = await af.Agent.get("MainAgent")

# By ID
agent = await af.Agent.get("agent_abc123")

# List all agents
agents = await af.Agent.list()
for agent in agents:
    print(f"{agent.name} ({agent.id})")

Creating agents

agent = await af.Agent.create(
    name="AnalyticsAgent",
    system_prompt="You analyze business data and produce actionable insights.",
    description="Data analysis specialist",
    enable_planning=True,
    enable_reflection=True,
    enable_retrieval=True,
    llm_config={
        "model": "openai/gpt-4.1",
        "temperature": 0.3,
        "max_tokens": 4000,
    },
)

Running agents

Simple response

response = await agent.run("What's our revenue trend?")
print(response)

Streaming

async for chunk in await agent.run("Analyze Q3 pipeline", stream=True):
    print(chunk, end="", flush=True)

Structured output

from pydantic import BaseModel

class Forecast(BaseModel):
    projected_revenue: float
    confidence: str
    key_risks: list[str]

forecast = await agent.run(
    "Forecast Q4 revenue based on current pipeline",
    response_model=Forecast,
)

With conversation context

conv_id = "conv_quarterly_review"

await agent.run("Show me the pipeline", conversation_id=conv_id)
await agent.run("Filter to deals over $100K", conversation_id=conv_id)
await agent.run("What's the total value?", conversation_id=conv_id)

Updating agents

await agent.update(
    system_prompt="Updated instructions...",
    enable_planning=True,
    llm_config={"model": "anthropic/claude-sonnet-4", "temperature": 0.2},
)

# Or modify locally and save
agent.system_prompt = "New prompt..."
await agent.save()

Sub-agent management

# Create a sub-agent
support = await agent.create_sub_agent(
    name="TierTwoSupport",
    system_prompt="You handle escalated support tickets...",
    enable_retrieval=True,
)

# List sub-agents
sub_agents = await agent.list_sub_agents()

Tool management

# Register a tool (from a function)
async def lookup_order(order_id: str) -> dict:
    """Look up order details from the fulfillment system."""
    return await fulfillment.get(order_id)

tool = await agent.register_tool(lookup_order, require_approval=True)

# List tools
tools = await agent.list_tools()

# Get a specific tool
tool = await agent.get_tool("lookup_order")

# Remove a tool
await agent.unregister_tool("lookup_order")

Knowledge base management

# Bind a knowledge base
await agent.register_knowledge_base("Product Docs")

# Search through the agent
results = await agent.search_knowledge_base(
    "Product Docs",
    query="How does pricing work?",
    limit=5,
)

# List bound KBs
kbs = await agent.list_knowledge_bases()

# Unbind
await agent.unregister_knowledge_base("Product Docs")

Prompt configuration

# List available prompt blocks
blocks = await agent.get_prompt_blocks()
for block in blocks:
    print(f"[{block['category']}] {block['id']}")

# Get current prompt config
config = await agent.get_prompt_config()

# Save custom prompt config
await agent.save_prompt_config(
    selected_blocks=["soul", "role", "communication", "tool_guidance"],
    custom_instructions="Always respond in bullet points.",
)

# Preview without saving
preview = await agent.preview_prompt(
    selected_blocks=["soul", "role", "tool_guidance"],
)
print(f"Tokens: {preview['estimated_tokens']}")

# Reset to defaults
await agent.reset_prompt_config()

Context blocks

# List registered context blocks
blocks = await agent.list_context_blocks()

# Build and inspect rendered context
rendered = await agent.build_context()
for name, content in rendered.items():
    print(f"--- {name} ---")
    print(content[:200])

# Pre-warm context for faster first message
await agent.warm_context()

Skills

# List skills for this agent
skills = await agent.list_skills()
for skill in skills:
    print(f"{skill['name']}: {skill['description'][:60]}...")
See also: Skill class for global skill operations.

Conversation management

# List conversations for this agent
conversations = await agent.get_conversations(limit=20)

# Get a specific conversation with messages
conv = await agent.get_conversation("conv_001")

# Delete a conversation
await agent.delete_conversation("conv_001")

Properties

PropertyTypeDescription
idstrAgent UUID
namestrAgent name
description`strNone`Agent description
system_prompt`strNone`System prompt (readable/writable)
configAgentConfigFull configuration dataclass