Agents API

Build an Agent

Use the Agentor class to initialize an Agent providing the name, instructions, and tools. You can run the Agent with the run method or stream the response with the stream method.

from agentor.tools import GetWeatherTool
from agentor import Agentor

agent = Agentor(
    name="Weather Agent",
    model="gpt-5-mini",
    tools=[GetWeatherTool()]
)
result = agent.run("What is the weather in London?")
print(result)

GetWeatherTool() reads a free WeatherAPI.com key from WEATHER_API_KEY, and raises if it is not set.

Connect to a tool

Agents has access to tools to perform tasks and get information from the world.

Learn more about LLM tool use here.

You can define your own tools or use the ones provided by Celesto AI ToolHub.

from agentor.tools import GetWeatherTool
from agentor import Agentor

agent = Agentor(
    name="Weather Agent",
    model="gpt-5-mini",
    tools=[GetWeatherTool()],  # 100+ Celesto AI managed tools — plug-and-play
)
result = agent.run("What is the weather in London?")
print(result)

from agentor import Agentor, function_tool

@function_tool
def get_weather(city: str):
    """Get the weather of city"""
    return f"Weather in {city} is sunny"

agent = Agentor(
    name="Weather Agent",
    model="gpt-5-mini",
    tools=[get_weather],  # Bring your own tool
)
result = agent.run("What is the weather in London?")
print(result)

Stream the response

You can stream the response from the Agent with the stream method.

from agentor.tools import GetWeatherTool
from agentor import Agentor
import asyncio

agent = Agentor(name="Weather Agent", tools=[GetWeatherTool()])

async def main():
    async for event in agent.stream_chat("How is the weather in Tokyo?"):
        print(event, flush=True)

if __name__ == "__main__":
    asyncio.run(main())

Each event is a JSON object with the following fields:

type: always run_item_stream_event.
message: text — a tool’s return value, or the agent’s answer.
tool_action: name and type for a tool call (tool_called) or its result (tool_output).
chunk: reserved, always null.
reasoning: reserved, always null.
raw_event: reserved, always null.

Show output

{
  "type": "run_item_stream_event",
  "message": null,
  "chunk": null,
  "tool_action": {"name": "get_weather", "type": "tool_called"},
  "reasoning": null,
  "raw_event": null
}

{
  "type": "run_item_stream_event",
  "message": "The weather in Tokyo is sunny and 22C.",
  "chunk": null,
  "tool_action": {"name": "get_weather", "type": "tool_output"},
  "reasoning": null,
  "raw_event": null
}

{
  "type": "run_item_stream_event",
  "message": "The weather in Tokyo is sunny with a temperature of 22°C.",
  "chunk": null,
  "tool_action": null,
  "reasoning": null,
  "raw_event": null
}

stream_chat streams steps, not tokens. For token-by-token text, see token-level streaming.

Tracing and observability

Agentor supports tracing out of the box. Traces capture agent runs and tool calls so you can inspect them in Celesto.

Set your Celesto API key

Add your Celesto API key to the environment.

export CELESTO_API_KEY="cel_..."

Enable tracing

Choose the setup that fits your workflow.

Automatic (recommended)
Explicit

If CELESTO_API_KEY is set, Agentor enables tracing automatically.

from agentor import Agentor

agent = Agentor(
    name="Support Agent",
    model="gpt-5-mini",
)
result = agent.run("Summarize the latest support tickets.")

Setting the key alone does not start tracing. Opt in with enable_tracing=True, or per call with tracing=True.

Enable tracing directly on the agent.

from agentor import Agentor

agent = Agentor(
    name="Support Agent",
    model="gpt-5-mini",
    enable_tracing=True,
)
result = agent.run("Summarize the latest support tickets.")

After you run the agent, open the Celesto dashboard to view the trace.

Troubleshooting tracing setup

No traces appear in the dashboard

Confirm you set CELESTO_API_KEY in the same environment where you run the agent.
Confirm you opted in with enable_tracing=True, an explicit tracer=, or tracing=True on the call - tracing is off by default.
A failed upload is logged as a warning, never raised. Turn on warning-level logging to see it.

See Tracing for the full span model and custom endpoints.

Next steps

Structured output

Return a validated Pydantic object instead of free text.

Durable runs

Save a run so another process can finish it after a crash.

Model providers

Point the agent at OpenRouter, Groq, Ollama, or any compatible endpoint.

Tool use

Build custom tools and connect MCP servers.

Start Here

Build Agents

Concepts

Tool Use & MCP

Guides

SuperAuth

Build an Agent

Connect to a tool

Stream the response

Tracing and observability

Troubleshooting tracing setup

Next steps

Structured output

Durable runs

Model providers

Tool use

​Build an Agent

​Connect to a tool

​Stream the response

​Tracing and observability

​Troubleshooting tracing setup

​Next steps

Structured output

Durable runs

Model providers

Tool use

Build an Agent

Connect to a tool

Stream the response

Tracing and observability

Troubleshooting tracing setup

Next steps