Quick Start

Getting Started

Create your first AI agent with Erdo. This guide covers installation, authentication, and building a basic agent.

Prerequisites You should have Python 3.8+ and access to the Erdo platform (sign up here)

Step 1: Choose Your Approach

Choose between CLI and Python SDK based on your preference:

CLI
Python SDK

The fastest way to get started is with the Erdo CLI:

brew install erdoai/tap/erdo

Verify the installation:

erdo --version

Install the Python SDK for pure Python workflows:

pip install erdo

Verify the installation:

import erdo
from erdo.sync import Sync
from erdo.invoke import Invoke
print(f"Erdo SDK version: {erdo.__version__}")

Step 2: Authenticate

Connect the CLI to your Erdo account:

erdo login

This will open your browser to authenticate with your Erdo account.

The SDK uses the same authentication as the CLI:

erdo login

Or set environment variables:

export ERDO_AUTH_TOKEN="your-token"

Verify authentication:

from erdo.config import Config
config = Config()
print(f"Authenticated: {config.is_authenticated()}")

Step 3: Create Your First Agent

Let’s create a simple task automation agent:

erdo init my-first-agent
cd my-first-agent

This creates a new agent project with the basic structure.

Step 4: Agent Components

Agents are built with these components:

Agents

from erdo import Agent

agent = Agent(
    name="task_automator",
    description="Automates tasks and processes data"
)

Steps

from erdo.actions import llm

automation_step = agent.step(
    llm.message(
        model="claude-sonnet-4",
        query=f"Help automate this task: {state.task_description}"
    )
)

Actions

from erdo import state
from erdo.actions import llm, memory, codeexec, websearch

# Language model actions
llm_step = agent.step(
    llm.message(model="claude-sonnet-4", query=state.query)
)

# Memory operations
memory_step = agent.step(
    memory.search(query=state.search_term, limit=5)
)

# Code execution
code_step = agent.step(
    codeexec.execute(code="print('Hello!')")
)

# Web search
search_step = agent.step(
    websearch.search(query=f"{state.topic} research")
)

Result Handlers

from erdo.conditions import IsSuccess, GreaterThan
from erdo.actions import memory, utils

# Direct handlers with step.on()
automation_step.on(
    IsSuccess() & GreaterThan("confidence", "0.8"),
    utils.send_status(status="completed", message="Task automated successfully")
)

# Chain multiple actions
automation_step.on(
    IsSuccess() & GreaterThan("confidence", "0.8"),
    memory.store(memory={
        "content": result.output.analysis,
        "type": "automation_result"
    })
)

Step 5: Complete Example

Here’s a complete agent that demonstrates the API patterns:

from erdo import Agent, state
from erdo.actions import llm, memory, utils
from erdo.conditions import IsSuccess, GreaterThan, IsError

# Create your agent
task_agent = Agent(
    name="task_automator",
    description="Automates tasks and provides intelligent responses"
)

# Step 1: Analyze the task
analyze_step = task_agent.step(
    llm.message(
        model="claude-sonnet-4",
        query=f"Analyze this task and provide automation recommendations: {state.task_description}",
        response_format={
            "Type": "json_schema",
            "Schema": {
                "type": "object",
                "properties": {
                    "task_type": {"type": "string"},
                    "complexity": {"type": "number"},
                    "recommendations": {"type": "array", "items": {"type": "string"}}
                }
            }
        }
    )
)

# Step 2: Generate automation plan
plan_step = task_agent.step(
    llm.message(
        model="claude-sonnet-4",
        query=f"Create a detailed automation plan for: {analyze_step.output.recommendations}"
    ),
    depends_on=analyze_step
)

# Handle high-complexity tasks
analyze_step.on(
    IsSuccess() & GreaterThan("complexity", "0.8"),
    memory.store(memory={
        "content": result.output.recommendations,
        "type": "complex_automation",
        "tags": ["complex", "automation"]
    })
)

# Handle successful planning with direct handler
plan_step.on(
    IsSuccess(),
    utils.send_status(status="plan_ready", message="Automation plan generated successfully"),
    memory.store(memory={
        "content": plan_step.output.plan,
        "type": "automation_plan"
    })
)

# Handle errors
plan_step.on(
    IsError(),
    utils.send_status(
        status="failed",
        message=f"Planning failed: {error.message}"
    )
)

Step 6: Test Your Agent

Erdo provides two complementary testing approaches:

Unit Testing
Integration Testing

Test all execution paths without LLM calls:

# Validate agent logic and templates
erdo test task_automator.py

# Output shows comprehensive validation:
# 🌳 Building flow tree for execution simulation...
# 📊 Generating execution paths...
# ✅ All 12 execution paths tested successfully!

What gets tested:

All conditional branches and result handlers
Template expressions with generated test data
State transformations and step dependencies
Error handling paths

This validation happens without LLM API calls, enabling rapid iteration.

Write integration tests with replay mode for efficient execution:

from erdo import invoke
from erdo.test import text_contains

def agent_test_task_automation():
    """Test task automation with real LLM execution."""
    response = invoke(
        "task_automator",
        messages=[{
            "role": "user",
            "content": "Organize my email inbox"
        }],
        mode="replay"  # Caches response after first run
    )

    # Check success and result status
    assert response.success
    assert response.result['status'] == 'success'

    # Extract and check text content
    if response.result.get('output'):
        content_text = ""
        for item in response.result['output'].get('content', []):
            if item.get('content_type') == 'text':
                content_text += item['content']
        assert text_contains(content_text, "organize")

    # Verify steps were executed
    assert len(response.steps) > 0

# Run tests in parallel
erdo agent-test tests/test_task_automator.py

Replay mode: First execution calls LLM and caches the response. Subsequent runs use the cached response, eliminating API costs during development.

Step 7: Deploy Your Agent

Sync your validated agent to the platform:

# Deploy to platform
erdo sync

# Invoke remotely
erdo invoke task_automator \
  --message "Organize my email inbox"

Deploy directly from Python:

from erdo.sync import Sync
from erdo.invoke import invoke

# Sync your agent to the platform
result = Sync(task_agent)
print(f"Synced agent: {result.agent_key}")

# Invoke your agent
response = invoke(
    result.agent_key,
    messages=[{
        "role": "user",
        "content": "Organize my email inbox"
    }]
)

# Access the structured result
if response.success:
    print(f"Status: {response.result['status']}")

    # Extract text content
    if response.result.get('output'):
        for item in response.result['output'].get('content', []):
            if item.get('content_type') == 'text':
                print(f"Response: {item['content']}")

    # Show execution steps
    print(f"Executed {len(response.steps)} steps")

Next Steps

Core Concepts

Learn about agents, steps, actions, and result handlers

SDK Reference

Explore the full Python SDK capabilities

Examples

See real-world automation examples

CLI Tools

Master the Erdo command-line interface

Key Concepts

Agents orchestrate your automation workflow
Steps define individual actions in your workflow
Actions are the building blocks (LLM calls, code execution, etc.)
Result handlers use step.on() for conditional logic
Dependencies control step execution order with depends_on
Output access uses step.output.field for referencing step results

Troubleshooting

Authentication issues

Make sure you’re logged in: erdo loginCheck your authentication status: erdo whoami

Agent validation errors

Run erdo validate to check for common issues:

Missing required fields
Invalid action configurations
Circular dependencies

Local testing issues

Ensure your agent has all required parameters:

erdo run --input "test input" --param key=value

Get Started

Core Concepts

Testing & Validation

Examples & Use Cases

Python SDK

TypeScript SDK

CLI Tools

Pre-built Agents

Advanced

Integrations

Getting Started

Step 1: Choose Your Approach

Step 2: Authenticate

Step 3: Create Your First Agent

Step 4: Agent Components

Step 5: Complete Example

Step 6: Test Your Agent

Step 7: Deploy Your Agent

Next Steps

Core Concepts

SDK Reference

Examples

CLI Tools

Key Concepts

Troubleshooting

Get Started

Core Concepts

Testing & Validation

Examples & Use Cases

Python SDK

TypeScript SDK

CLI Tools

Pre-built Agents

Advanced

Integrations

​Getting Started

​Step 1: Choose Your Approach

​Step 2: Authenticate

​Step 3: Create Your First Agent

​Step 4: Agent Components

​Step 5: Complete Example

​Step 6: Test Your Agent

​Step 7: Deploy Your Agent

​Next Steps

Core Concepts

SDK Reference

Examples

CLI Tools

​Key Concepts

​Troubleshooting

Getting Started

Step 1: Choose Your Approach

Step 2: Authenticate

Step 3: Create Your First Agent

Step 4: Agent Components

Step 5: Complete Example

Step 6: Test Your Agent

Step 7: Deploy Your Agent

Next Steps

Key Concepts

Troubleshooting