Documentation Index
Fetch the complete documentation index at: https://laddr.agnetlabs.com/llms.txt
Use this file to discover all available pages before exploring further.
Learn best practices for designing and authoring effective Laddr agents.
Agent Design Principles
Single Responsibility
Each agent should have a clear, focused purpose:
# ✅ Good - Focused agent
researcher = Agent(
name="researcher",
role="Web Research Specialist",
goal="Search the web and find accurate information",
# ...
)
# ❌ Bad - Too broad
general_agent = Agent(
name="general_agent",
role="Does everything",
goal="Handle all tasks",
# ...
)
Clear Role Definition
Define the agent’s role clearly:
researcher = Agent(
name="researcher",
role="Web Research Specialist", # What the agent is
goal="Find and summarize information from the web", # What it does
backstory="""You are an expert researcher with years of experience
finding accurate information online. You prioritize recent, authoritative
sources and present findings clearly.""", # How it behaves
)
# ✅ Good - Relevant tools
researcher = Agent(
name="researcher",
tools=[web_search, scrape_url, extract_links], # All research-related
)
# ❌ Bad - Unnecessary tools
researcher = Agent(
name="researcher",
tools=[web_search, calculator, weather_api], # Calculator not needed
)
Agent Patterns
Coordinator Pattern
A coordinator agent delegates tasks to specialized workers:
coordinator = Agent(
name="coordinator",
role="Task Coordinator",
goal="Break down complex tasks and delegate to specialists",
backstory="""You are an experienced project manager who breaks down
complex tasks into smaller, manageable pieces and assigns them to
the right specialists.""",
instructions="""
When given a task:
1. Analyze the requirements
2. Break it into subtasks
3. Delegate to appropriate agents
4. Synthesize results
""",
is_coordinator=True, # Enables delegation tools
)
Worker Pattern
Specialized workers that handle specific tasks:
researcher = Agent(
name="researcher",
role="Research Specialist",
goal="Conduct thorough research on given topics",
# Focused on one task type
)
writer = Agent(
name="writer",
role="Content Writer",
goal="Write clear, engaging content",
# Focused on writing
)
Pipeline Pattern
Agents in a sequential pipeline:
# Agent 1: Research
researcher = Agent(name="researcher", ...)
# Agent 2: Analyze
analyzer = Agent(name="analyzer", ...)
# Agent 3: Write
writer = Agent(name="writer", ...)
# Usage: researcher → analyzer → writer
Instructions Design
Clear Instructions
Write specific, actionable instructions:
agent = Agent(
name="analyzer",
instructions="""
When analyzing data:
1. First, identify the data type and structure
2. Look for patterns, trends, and anomalies
3. Calculate relevant statistics
4. Summarize findings in 2-3 bullet points
5. Highlight any concerns or recommendations
""",
)
Avoid Ambiguity
Be explicit about expected behavior:
# ✅ Good - Clear expectations
agent = Agent(
instructions="""
Always cite sources when providing information.
Use the format: [Source Name](URL)
""",
)
# ❌ Bad - Vague
agent = Agent(
instructions="Be helpful and accurate",
)
Include Examples
Provide examples in instructions:
agent = Agent(
instructions="""
Format responses as JSON with these fields:
- summary: Brief summary (max 100 words)
- key_points: Array of 3-5 key points
- sources: Array of source URLs
Example:
{
"summary": "...",
"key_points": ["...", "..."],
"sources": ["https://...", "https://..."]
}
""",
)
Select tools that align with the agent’s purpose:
# Research agent needs web tools
researcher = Agent(
name="researcher",
tools=[web_search, scrape_url, extract_links],
)
# Data analyst needs data tools
analyst = Agent(
name="analyst",
tools=[read_csv, calculate_stats, generate_chart],
)
# ✅ Good - 3-5 focused tools
agent = Agent(
tools=[tool1, tool2, tool3], # Manageable set
)
# ❌ Bad - Too many tools
agent = Agent(
tools=[tool1, tool2, ..., tool20], # Overwhelming
)
Error Handling
Set Appropriate Retries
agent = Agent(
name="researcher",
max_retries=2, # Retry transient failures
timeout=60, # Prevent hanging
)
agent = Agent(
instructions="""
If a tool fails:
1. Try an alternative approach
2. If no alternative, report the error clearly
3. Suggest what information is missing
""",
)
Control Iterations
Limit reasoning loops:
agent = Agent(
max_iterations=3, # Prevent infinite loops
max_tool_calls=5, # Limit tool usage
timeout=45, # Set timeout
)
Use Appropriate Models
Choose models based on task complexity:
# Simple tasks - Fast, cheap model
simple_agent = Agent(
llm=gemini(model="gemini-2.5-flash"), # Fast
)
# Complex reasoning - Better model
complex_agent = Agent(
llm=gemini(model="gemini-2.0-flash-exp"), # More capable
)
Testing Agents
Unit Testing
Test agent logic in isolation:
async def test_researcher():
result = await researcher.process_task({
"query": "Test query"
})
assert result["status"] == "success"
assert "summary" in result
Integration Testing
Test with real tools and services:
async def test_researcher_integration():
# Use test API keys
result = await researcher.process_task({
"query": "Python async"
})
# Verify tool calls worked
assert len(result["tool_calls"]) > 0
Common Pitfalls
Over-Complex Instructions
Keep instructions focused:
# ❌ Bad - Too complex
instructions="""
When processing tasks, first analyze the context, then consider
all possible approaches, evaluate each one, consider edge cases,
think about error handling, plan the execution, execute carefully,
verify results, and finally format the output...
"""
# ✅ Good - Clear and focused
instructions="""
Process the task in 3 steps:
1. Analyze the input
2. Execute the required action
3. Format the result
"""
Conflicting Instructions
Ensure instructions don’t conflict:
# ❌ Bad - Conflicting
instructions="""
Always be concise. Provide detailed explanations with examples.
"""
# ✅ Good - Consistent
instructions="""
Provide concise summaries with 2-3 key examples when relevant.
"""
Next Steps
