Skip to main content

Agent Basics

Learn the fundamentals of building Sypho agents.

Agent Structure​

A Sypho agent is a Python module with:

  • Entrypoints - Entry points for execution (marked with @entrypoint)
  • Tools - Functions the LLM can call (marked with @tool)
  • Agent Config - LLM settings and system prompt

Minimal Agent​

from sypho_sdk import entrypoint, AgentContext

@entrypoint
async def main(input: dict, context: AgentContext):
    """Main entrypoint"""
    message = input.get("message", "Hello")
    return {"response": f"Received: {message}"}

With Tools​

from sypho_sdk import entrypoint, tool, AgentContext

@tool
async def calculate(a: int, b: int, operation: str):
    """
    Perform arithmetic operations

    Args:
        a: First number
        b: Second number
        operation: Operation (add, subtract, multiply, divide)
    """
    if operation == "add":
        return a + b
    elif operation == "subtract":
        return a - b
    elif operation == "multiply":
        return a * b
    elif operation == "divide":
        return a / b if b != 0 else "Error: division by zero"

@entrypoint
async def main(input: dict, context: AgentContext):
    """Calculator agent"""
    # In agent mode, the LLM automatically calls tools
    # based on the user's input and system prompt
    pass

Agent Config​

Agents run in agent mode with an LLM loop. Configure via manifest:

{
  "agent_config": {
    "model": "anthropic/claude-3-5-sonnet-20241022",
    "max_tokens": 4096,
    "max_iterations": 10,
    "system_prompt": "You are a calculator assistant. Help users with math."
  }
}

The SDK auto-generates this from your entrypoint function's docstring.

Execution Flow​

  1. User creates run with input
  2. Runner claims step and spawns container
  3. SDK loads entrypoint function
  4. SDK enters run_loop() (agent mode)
  5. LLM receives system prompt + user input + tools
  6. LLM decides which tools to call
  7. SDK executes tool calls
  8. Loop continues until LLM returns final answer
  9. Result returned to control plane

Calling Tools​

LLM-Driven (Agent Mode)​

LLM automatically decides which tools to call:

@entrypoint
async def main(input: dict, context: AgentContext):
    # LLM will analyze input and call tools as needed
    pass

Manual Tool Calls​

@entrypoint
async def main(input: dict, context: AgentContext):
    result = await context.call_tool("calculate", {
        "a": 10,
        "b": 5,
        "operation": "add"
    })
    return {"result": result}

Platform Tools​

Access Sypho's built-in tools:

@entrypoint
async def main(input: dict, context: AgentContext):
    # Save data
    await context.call_tool("structured_data_save", {
        "namespace": "my-data",
        "key": "user:123",
        "data": {"name": "Alice"}
    })

    # Fetch data
    user = await context.call_tool("structured_data_get", {
        "namespace": "my-data",
        "key": "user:123"
    })

    return user

Best Practices​

1. Clear Docstrings​

@tool
async def fetch_data(query: str):
    """
    Fetch data from external API

    Args:
        query: Search query string

    Returns:
        List of matching results
    """
    pass

Docstrings become tool descriptions for the LLM.

2. Type Hints​

@tool
async def process(text: str, limit: int = 100) -> dict:
    pass

Type hints generate JSON schema for tool parameters.

3. Error Handling​

@tool
async def risky_operation(data: str):
    try:
        result = await external_api(data)
        return {"status": "success", "data": result}
    except Exception as e:
        return {"status": "error", "message": str(e)}

Return errors as structured data instead of raising exceptions.

4. System Prompts​

Be specific about the agent's role and capabilities:

You are a customer support agent.
You can:
- Look up order status
- Process refunds
- Answer product questions

Always be polite and helpful.

Next Steps​