> ## Documentation Index
> Fetch the complete documentation index at: https://docs.celesto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents API

> Build an Agentor agent in Python, attach tools and skills, and serve it as a production-ready REST API with just a few lines of code.

## 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.

```python theme={null}
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)
```

<Note>
  `GetWeatherTool()` reads a free [WeatherAPI.com](https://www.weatherapi.com/) key from `WEATHER_API_KEY`, and raises if it is not set.
</Note>

## Connect to a tool

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

<Tip>
  Learn more about [LLM tool use here](./tools/overview).
</Tip>

You can define your own tools or use the ones provided by Celesto AI [ToolHub](https://celesto.ai/toolhub).

<CodeGroup>
  ```python With Celesto AI ToolHub theme={null}
  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)
  ```

  ```python Bring your own tool theme={null}
  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)
  ```
</CodeGroup>

## Stream the response

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

```python theme={null}
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`.

<Expandable title="output">
  ```json theme={null}
  {
    "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
  }
  ```
</Expandable>

<Note>
  `stream_chat` streams steps, not tokens. For token-by-token text, see [token-level streaming](/agentor/guides/streaming#token-level-streaming).
</Note>

## Tracing and observability

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

<Steps>
  <Step title="Set your Celesto API key">
    Add your Celesto API key to the environment.

    ```bash theme={null}
    export CELESTO_API_KEY="cel_..."
    ```
  </Step>

  <Step title="Enable tracing">
    Choose the setup that fits your workflow.

    <Tabs>
      <Tab title="Automatic (recommended)">
        If `CELESTO_API_KEY` is set, Agentor enables tracing automatically.

        ```python theme={null}
        from agentor import Agentor

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

        <Tip>
          Setting the key alone does not start tracing. Opt in with
          `enable_tracing=True`, or per call with `tracing=True`.
        </Tip>
      </Tab>

      <Tab title="Explicit">
        Enable tracing directly on the agent.

        ```python theme={null}
        from agentor import Agentor

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

    <Check>
      After you run the agent, open the Celesto dashboard to view the trace.
    </Check>
  </Step>
</Steps>

### Troubleshooting tracing setup

<AccordionGroup>
  <Accordion title="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.
  </Accordion>
</AccordionGroup>

See [Tracing](/agentor/tracing) for the full span model and custom endpoints.

## Next steps

<CardGroup cols={2}>
  <Card title="Structured output" icon="brackets-curly" href="/agentor/structured-output">
    Return a validated Pydantic object instead of free text.
  </Card>

  <Card title="Durable runs" icon="floppy-disk" href="/agentor/durable-runs">
    Save a run so another process can finish it after a crash.
  </Card>

  <Card title="Model providers" icon="plug" href="/agentor/model-providers">
    Point the agent at OpenRouter, Groq, Ollama, or any compatible endpoint.
  </Card>

  <Card title="Tool use" icon="screwdriver-wrench" href="/agentor/tools/overview">
    Build custom tools and connect MCP servers.
  </Card>
</CardGroup>