Skip to content

Quick Start

Build a working agent in five minutes.

Step 1 — Define a tool

A tool is a plain Python function decorated with @tool. The model can call it during a conversation.

from exagent import tool

@tool
def get_weather(city: str, units: str = "celsius") -> str:
    """Return the current weather for a city."""
    return f"{city}: 18°C, sunny"  # replace with a real API call

The decorator reads the type hints to build the JSON schema and uses the docstring as the description the model sees. No manual schema writing needed.

Step 2 — Build an agent

Subclass Agent, set a model, and register your tools.

from exagent import Agent, tool

@tool
def get_weather(city: str, units: str = "celsius") -> str:
    """Return the current weather for a city."""
    return f"{city}: 18°C, sunny"

class WeatherAgent(Agent):
    def __init__(self):
        self.system_description = "You are a helpful weather assistant."
        self.set_model("openai", "gpt-4.1-mini")
        self.add_tool(get_weather)
        super().__init__()

Always call super().__init__() last

Tools, models, and skills must be registered before super().__init__() so the system prompt is built correctly.

Step 3 — Run it

agent = WeatherAgent()
answer = agent.run("What's the weather in Paris and London?")
print(answer)

The agent will:

  1. Send your prompt + the tool definition to the model
  2. Receive a tool call request (get_weather(city="Paris"))
  3. Execute the handler and feed the result back
  4. Repeat for London
  5. Return the final natural-language answer

Step 4 — Stream the output

Swap run() for stream() to see tokens and tool events as they happen:

for event in agent.stream("What's the weather in Paris?"):
    if event["type"] == "text_delta":
        print(event["text"], end="", flush=True)
    elif event["type"] == "tool_call":
        print(f"\n→ calling {event['tool_call'].name}...")
    elif event["type"] == "done":
        print()

Step 5 — Try the interactive shell

Instead of hardcoding prompts, launch an interactive session:

from exagent import shell

shell(WeatherAgent())

exagent shell  |  gpt-4.1-mini  |  streaming
Type /help for commands, /exit or Ctrl-C to quit.

> What's the weather in Tokyo?
→ calling get_weather...
The weather in Tokyo is 18°C and sunny.

> /exit

Full example

from exagent import Agent, tool, shell

@tool
def get_weather(city: str) -> str:
    """Return the current weather for a city."""
    return f"{city}: 18°C, sunny"

@tool
def list_cities() -> list:
    """Return a list of cities with available weather data."""
    return ["Paris", "London", "Tokyo", "New York"]

class WeatherAgent(Agent):
    def __init__(self):
        self.system_description = (
            "You are a helpful weather assistant. "
            "Use get_weather to check conditions and list_cities to see "
            "which cities are supported."
        )
        self.set_model("openai", "gpt-4.1-mini")
        self.add_tools([get_weather, list_cities])
        super().__init__()

if __name__ == "__main__":
    shell(WeatherAgent())

Next steps