Skip to main content
An Agent wraps a model with tools, instructions, and configuration to create an autonomous system that can reason, take actions, and produce structured results.

​
How Agents Work

The agent follows a loop: The loop continues until the model returns a text response with no tool calls, or the maximum iteration limit is reached.

​
Creating an Agent

from definable.models import OpenAIChat
from definable.agents import Agent
from definable.tools import tool

@tool
def search_docs(query: str) -> str:
    """Search the documentation for relevant information."""
    return f"Found: Documentation about {query}."

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    tools=[search_docs],
    instructions="You are a documentation assistant. Use the search tool to find answers.",
    # memory=memory,    # Optional: persistent memory (see Memory docs)
    # readers=True,     # Optional: file reader support (see Readers docs)
    # name="my-agent",  # Optional: display name for logging
)

output = agent.run("How do I configure middleware?")
print(output.content)

​
Key Concepts

Configuration

Control retries, iteration limits, tracing, knowledge, compression, and more through AgentConfig.

Running Agents

Four execution modes: sync, async, sync streaming, and async streaming.

Multi-Turn

Maintain conversation history across multiple interactions using session IDs and message lists.

Middleware

Wrap agent execution with logging, retries, metrics, and custom logic.

Tracing

Export structured events from every run for debugging and observability.

Testing

Test agents without API calls using MockModel and AgentTestCase.

Memory

Persistent multi-tier memory with automatic recall, distillation, and cross-session context.

Readers

Extract text from PDF, DOCX, XLSX, and audio files attached to agent messages.

Runtime

Deploy with HTTP endpoints, webhooks, cron jobs, and messaging interfaces via agent.serve().

Authentication

Secure HTTP endpoints with API key or JWT authentication.

​
Agent Properties

Once created, the agent exposes useful metadata: 
print(agent.agent_id)     # Unique identifier
print(agent.agent_name)   # Human-readable name
print(agent.tool_names)   # ['search_docs']

​
Adding Middleware

Chain middleware onto an agent with the fluent .use() method: 
from definable.agents import LoggingMiddleware, RetryMiddleware

agent = (
    Agent(model=model, tools=[search_docs])
    .use(LoggingMiddleware(logger))
    .use(RetryMiddleware(max_retries=3))
)

​
Deploying with serve()

Use agent.serve() to start the full agent runtime — messaging interfaces, HTTP endpoints, webhooks, and cron jobs: 
from definable.triggers import Webhook

@agent.on(Webhook("/webhook"))
async def handle(event):
  return f"Process: {event.body}"

agent.serve(telegram_interface, port=8000)
See Agent Runtime for the full runtime documentation including webhooks, cron scheduling, and dev mode. See Multi-Interface Serving for interface-specific details.

​
Context Manager

Agents support context managers for proper resource cleanup, especially important when using toolkits with external connections: 
with Agent(model=model, toolkits=[mcp_toolkit]) as agent:
    output = agent.run("List files in the project.")