Agent
TheAgent 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]}...")
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
| Property | Type | Description | |
|---|---|---|---|
id | str | Agent UUID | |
name | str | Agent name | |
description | `str | None` | Agent description |
system_prompt | `str | None` | System prompt (readable/writable) |
config | AgentConfig | Full configuration dataclass |

