diff --git a/agentor/api/agentor.mdx b/agentor/api/agentor.mdx
index 66035aa..564aa38 100644
--- a/agentor/api/agentor.mdx
+++ b/agentor/api/agentor.mdx
@@ -23,9 +23,12 @@ Agentor(
skills: Optional[List[str]] = None,
enable_tracing: bool = False,
max_turns: int = 20,
+ max_tool_failures: int = 2,
store: Any = None,
base_url: Optional[str] = None,
tracer: Any = None,
+ trace_group_id: Optional[str] = None,
+ trace_metadata: Optional[Dict[str, Any]] = None,
engine: Optional[Literal["native"]] = None,
)
```
@@ -78,13 +81,17 @@ Agentor(
- Turn on Celesto tracing explicitly. Requires `CELESTO_API_KEY`, and raises if it is missing. Tracing is already automatic when that variable is set.
+ Turn on Celesto tracing for this agent. Requires `CELESTO_API_KEY`, and raises if it is missing. Tracing is off by default; setting `CELESTO_API_KEY` alone does not enable it. See [Tracing](/agentor/tracing).
How many model calls a run may make before giving up. A run that hits the limit ends with `status="max_turns"` instead of raising.
+
+ How many times any one tool may raise before Agentor stops offering it to the model. Applies per tool, per run — so a run with two tools has a budget of `max_tool_failures` for each. Set higher for tools that are legitimately flaky, or lower to fail fast.
+
+
Where to save the run's events, so an interrupted run can be resumed. Use `FileStore` or `MemoryStore` from `agentor.engine.store`. See [Durable runs](/agentor/durable-runs).
@@ -94,7 +101,15 @@ Agentor(
- A tracer built with `setup_celesto_tracing`. Takes precedence over the one Agentor builds from `CELESTO_API_KEY`. See [Tracing](/agentor/tracing).
+ A tracer built with `setup_celesto_tracing`. Passing one turns tracing on for the agent — you do not also need `enable_tracing=True`. See [Tracing](/agentor/tracing).
+
+
+
+ Optional group id attached to every trace this agent exports. Traces sharing an id are grouped together in the Celesto dashboard, so use it to correlate the runs that make up one user session, one job, or one request. See [Tracing](/agentor/tracing).
+
+
+
+ Optional dictionary of key-value pairs attached to every trace this agent exports. Useful for tagging environment, tenant, or experiment so the dashboard can filter by it.
@@ -112,9 +127,14 @@ Agentor(
Run the agent synchronously.
```python theme={null}
-def run(input: str) -> RunResult
+def run(input: str, tracing: Optional[bool] = None) -> RunResult
```
+**Parameters:**
+
+* `input` (str): the prompt
+* `tracing` (bool | None): override tracing for this call. `None` keeps the agent's configuration, `False` sends nothing for this run, `True` traces it even when the agent has tracing off (requires `CELESTO_API_KEY`). See [Tracing](/agentor/tracing).
+
**Returns:** a [`RunResult`](#runresult).
```python theme={null}
@@ -143,6 +163,7 @@ async def arun(
limit_concurrency: int = 10,
max_turns: Optional[int] = None,
fallback_models: Optional[List[str]] = None,
+ tracing: Optional[bool] = None,
) -> RunResult | List[RunResult]
```
@@ -152,6 +173,7 @@ async def arun(
* `limit_concurrency` (int): maximum concurrent runs when `input` is a list of prompts (default: 10)
* `max_turns` (int): turn budget for this call. Defaults to the agent's `max_turns`
* `fallback_models` (List\[str]): models to try if the primary one is rate limited or errors. Configured temperature and token limits carry across
+* `tracing` (bool | None): override tracing for this call. `None` keeps the agent's configuration, `False` sends nothing, `True` traces it even when the agent has tracing off. When `input` is a batch, the flag applies to every prompt
```python theme={null}
import asyncio
@@ -218,9 +240,17 @@ async def chat(
input: str,
stream: bool = False,
serialize: bool = True,
+ tracing: Optional[bool] = None,
)
```
+**Parameters:**
+
+* `input` (str): user message
+* `stream` (bool): return an async iterator instead of a `RunResult`
+* `serialize` (bool): when streaming, yield JSON strings (default) or `AgentOutput` objects
+* `tracing` (bool | None): override tracing for this call, same semantics as [`run`](#run)
+
**Returns:** a `RunResult`, or an async iterator when `stream=True`.
### stream\_chat
@@ -231,6 +261,7 @@ Stream the agent's progress as it works.
async def stream_chat(
input: str,
serialize: bool = True,
+ tracing: Optional[bool] = None,
) -> AsyncIterator[Union[str, AgentOutput]]
```
@@ -238,6 +269,7 @@ async def stream_chat(
* `input` (str): user message
* `serialize` (bool): yield JSON strings (default) or `AgentOutput` objects
+* `tracing` (bool | None): override tracing for this call, same semantics as [`run`](#run)
```python theme={null}
import asyncio
diff --git a/agentor/guides/observability.mdx b/agentor/guides/observability.mdx
index 5006052..f1ccf92 100644
--- a/agentor/guides/observability.mdx
+++ b/agentor/guides/observability.mdx
@@ -9,7 +9,7 @@ Those events go two ways. They are uploaded to Celesto as a [trace](/agentor/tra
## Send runs to Celesto
-Set one environment variable and every run is recorded:
+Set your Celesto API key and turn tracing on for the agent — a run is only recorded when both are true:
```bash
export CELESTO_API_KEY="cel_..."
@@ -22,6 +22,7 @@ agent = Agentor(
name="Support Agent",
model="gpt-5-mini",
tools=["get_weather"],
+ enable_tracing=True,
)
result = agent.run("What's the weather in Paris?")
@@ -178,7 +179,7 @@ print(failures[0].error) # RuntimeError: database unavailable
```
- The failure budget is fixed at two attempts per tool for agents built with `Agentor(...)`. It is configurable only on the lower-level `AgentLoop` via `max_tool_failures=`.
+ The failure budget defaults to two attempts per tool. Adjust it per agent with `Agentor(..., max_tool_failures=3)` — higher for tools that are legitimately flaky, lower to fail fast.
## Keep a copy of every run
diff --git a/agentor/installation.mdx b/agentor/installation.mdx
index 8c01fca..c32cee0 100644
--- a/agentor/installation.mdx
+++ b/agentor/installation.mdx
@@ -139,22 +139,22 @@ export CELESTO_API_KEY=your_api_key
Get your key from the [Celesto dashboard](https://celesto.ai/dashboard).
-With `CELESTO_API_KEY` set, Agentor traces every run automatically:
+Tracing is off unless you ask for it. Opt in on the agent, or on a single call:
```python
from agentor import Agentor
-# Tracing enabled automatically if CELESTO_API_KEY is set
agent = Agentor(
name="My Agent",
model="gpt-5-mini",
+ enable_tracing=True, # trace every run this agent makes
)
-```
-View traces at [celesto.ai/observe](https://celesto.ai/observe).
+# Or trace one call from an otherwise-untraced agent.
+agent.run("Debug this", tracing=True)
+```
-Tracing is off unless you ask for it. Opt in per agent with
-`enable_tracing=True`, or per call with `agent.run("...", tracing=True)`.
+View traces at [celesto.ai/observe](https://celesto.ai/observe). See [Tracing](/agentor/tracing) for the full guide.
## Next steps
diff --git a/agentor/tracing.mdx b/agentor/tracing.mdx
index 02b40df..ea535a5 100644
--- a/agentor/tracing.mdx
+++ b/agentor/tracing.mdx
@@ -1,12 +1,12 @@
---
title: "Tracing and Observability"
sidebarTitle: "Tracing"
-description: "See every Agentor run in the Celesto dashboard — model calls, tool calls, timings, and token counts — with one environment variable."
+description: "See every Agentor run in the Celesto dashboard — model calls, tool calls, timings, and token counts — once you opt in."
---
## What tracing gives you
-A trace is a recording of one agent run. Set one environment variable and every run shows up in the Celesto dashboard, so you can:
+A trace is a recording of one agent run. Turn it on and every run shows up in the Celesto dashboard, so you can:
* Follow an agent step by step instead of guessing from logs
* See what each tool was given and what it returned
@@ -18,7 +18,7 @@ A trace is a recording of one agent run. Set one environment variable and every
- Rebuilt in Agentor 0.1.0. Traces are now built from the agent's own event stream, so every run is covered — including streamed runs, resumed runs, and runs that raise.
+ Tracing is opt-in. A trace carries prompts, tool arguments, and tool results, so nothing leaves your process until you ask for it — a Celesto API key alone does not enable it.
***
@@ -34,8 +34,8 @@ A trace is a recording of one agent run. Set one environment variable and every
```
-
- That is the whole setup. With `CELESTO_API_KEY` set, Agentor traces every run and prints a one-line notice the first time it does.
+
+ Pass `enable_tracing=True` when building the agent. Every run it makes is then recorded.
```python
from agentor import Agentor
@@ -43,13 +43,12 @@ A trace is a recording of one agent run. Set one environment variable and every
agent = Agentor(
name="Support Agent",
model="gpt-5-mini",
+ enable_tracing=True,
)
result = agent.run("Summarize the latest support tickets.")
```
-
- Prefer to be explicit? `Agentor(..., enable_tracing=True)` turns tracing on and raises a clear error if the key is missing, instead of silently doing nothing.
-
+ Agentor raises with a clear message if `enable_tracing=True` is set without `CELESTO_API_KEY`, rather than silently doing nothing.
@@ -61,6 +60,21 @@ A trace is a recording of one agent run. Set one environment variable and every
+## Trace one run
+
+`tracing=` on the call overrides whatever the agent was built with. Use it to exempt a sensitive input from an otherwise-traced agent, or to record a single call from an agent that normally does not:
+
+```python
+# Agent has tracing on — skip this one call.
+agent.run("Contains customer data", tracing=False)
+
+# Agent has tracing off — trace just this call.
+debug_agent = Agentor(name="Debug", model="gpt-5-mini")
+debug_agent.run("Why is this failing?", tracing=True)
+```
+
+Pass `None` (the default) to keep the agent's configuration. `tracing=` is accepted by `run`, `arun`, `chat`, and `stream_chat`. A per-run tracer is used for that call only — a single `tracing=True` never enrolls later runs.
+
***
## What a trace contains
@@ -128,7 +142,7 @@ result = agent.run("Summarize the latest support tickets.")
How long to wait for the upload, in seconds.
-An explicit `tracer=` always wins over the one built from `CELESTO_API_KEY`, so you do not need to disable auto-tracing first.
+An explicit `tracer=` turns tracing on for the agent, so `enable_tracing=` is not needed alongside it.
A tracer is a plain object, safe to share between agents, and it needs no shutdown or flush call. Each run uploads its own trace when it finishes.
@@ -151,8 +165,20 @@ An explicit `tracer=` always wins over the one built from `CELESTO_API_KEY`, so
If you iterate `stream_chat()` and break out early, the run never finishes and its trace is not exported. `run()` and `arun()` always drain, so they always export.
-
- Traces carry an agent name and timing, but there is no supported way to attach a `group_id` or custom metadata per run from the `Agentor` API. Use distinct agent names if you need to tell workloads apart in the dashboard.
+
+ Set `trace_group_id` and `trace_metadata` on the agent to tag every trace it produces. Traces sharing a `group_id` are grouped together in the dashboard, and metadata comes along for filtering and search.
+
+ ```python
+ agent = Agentor(
+ name="Support Agent",
+ model="gpt-5-mini",
+ enable_tracing=True,
+ trace_group_id="session-42",
+ trace_metadata={"env": "prod", "customer": "acme"},
+ )
+ ```
+
+ Both are optional and default to `None`.