Update from code changes: agentor tracing opt-in and per-run control

agentor/api/agentor.mdx

@@ -1,7 +1,7 @@
 ---
 title: "Agentor class API reference"
 sidebarTitle: "Agentor"
 description: "Agentor class API reference: configure model, provider, tools, skills, structured output, durable storage, and tracing, then run agents synchronously, asynchronously, or as a streamed API."
 ---
 
 ## Overview
@@ -16,16 +16,19 @@
     instructions: Optional[str] = None,
     model: Any = "gpt-5-nano",
     tools: Optional[List[Any]] = None,
     output_type: Any = None,
     debug: bool = False,
     api_key: Optional[str] = None,
     model_settings: Optional[ModelSettings] = None,
     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 @@
 </ParamField>
 
 <ParamField path="enable_tracing" type="bool" default="False">
-  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).
 </ParamField>
 
 <ParamField path="max_turns" type="int" default="20">
   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.
 </ParamField>
 
+<ParamField path="max_tool_failures" type="int" default="2">
+  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.
+</ParamField>
+
 <ParamField path="store" type="Store" default="None">
   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).
 </ParamField>
@@ -94,7 +101,15 @@
 </ParamField>
 
 <ParamField path="tracer" type="CelestoTracer" default="None">
-  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).
+</ParamField>
+
+<ParamField path="trace_group_id" type="str" default="None">
+  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).
+</ParamField>
+
+<ParamField path="trace_metadata" type="Dict[str, Any]" default="None">
+  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.
 </ParamField>
 
 <ParamField path="engine" type='Literal["native"]' default="None">
@@ -112,13 +127,18 @@
 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}
 from agentor import Agentor
 
 agent = Agentor(
     name="Assistant",
@@ -143,19 +163,21 @@
     limit_concurrency: int = 10,
     max_turns: Optional[int] = None,
     fallback_models: Optional[List[str]] = None,
+    tracing: Optional[bool] = None,
 ) -> RunResult | List[RunResult]
 ```
 
 **Parameters:**
 
 * `input`: one prompt, a list of prompts to run concurrently, or a list of message dicts to continue a conversation
 * `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
 from agentor import Agentor
 
 agent = Agentor(name="Assistant", model="gpt-5-mini")
 
@@ -199,7 +221,7 @@
 
 ```python  theme={null}
 from agentor import Agentor
 from agentor.engine.store import FileStore
 
 agent = Agentor(name="Agent", tools=[...], store=FileStore("runs"))
 
@@ -218,9 +240,17 @@
     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
@@ -228,20 +258,22 @@
 Stream the agent's progress as it works.
 
 ```python  theme={null}
 async def stream_chat(
     input: str,
     serialize: bool = True,
+    tracing: Optional[bool] = None,
 ) -> AsyncIterator[Union[str, AgentOutput]]
 ```
 
 **Parameters:**
 
 * `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
 from agentor import Agentor
 
 agent = Agentor(name="Assistant", model="gpt-5-mini")
 
@@ -262,8 +294,8 @@
 def serve(
     host: Literal["0.0.0.0", "127.0.0.1", "localhost"] = "0.0.0.0",
     port: int = 8000,
     log_level: Literal["debug", "info", "warning", "error"] = "info",
     access_log: bool = True,
 )
 ```
 
@@ -283,20 +315,20 @@
 
 ### from\_md
 
 Create an agent from a markdown file with YAML frontmatter.
 
 ```python  theme={null}
 @classmethod
 def from_md(
     cls,
     md_path: str | Path,
     *,
     model: Any = None,
     tools: Optional[List[Any]] = None,
     output_type: Any = None,
     debug: bool = False,
     api_key: Optional[str] = None,
     model_settings: Optional[ModelSettings] = None,
 ) -> Agentor
 ```
 
@@ -314,7 +346,7 @@
 ```
 
 ```python  theme={null}
 from agentor import Agentor
 
 agent = Agentor.from_md("agents/weather_agent.md")
 result = agent.run("What's the weather in Tokyo?")
@@ -377,7 +409,7 @@
 ### Basic agent
 
 ```python  theme={null}
 from agentor import Agentor
 
 agent = Agentor(
     name="Assistant",
@@ -406,7 +438,7 @@
 ### Agent with tools
 
 ```python  theme={null}
 from agentor import Agentor, function_tool
 
 @function_tool
 def get_weather(city: str) -> str:
@@ -442,7 +474,7 @@
 ### Serving an agent
 
 ```python  theme={null}
 from agentor import Agentor
 
 agent = Agentor(
     name="Customer Support",

agentor/guides/observability.mdx

@@ -1,15 +1,15 @@
 ---
 title: "Monitoring agents in production"
 description: "Watch Agentor agents in production: send traces to Celesto, read token usage and tool history off a run result, and tell a real failure from a run that ran out of turns."
 ---
 
 Once an agent is live you stop asking "does it work?" and start asking "what did it just do, and what did it cost?". Agentor answers both from one place: the stream of events every run emits.
 
 Those events go two ways. They are uploaded to Celesto as a [trace](/agentor/tracing) you can click through, and they come back on the result object so your own code can read them.
 
 ## 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 @@
     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 @@
 ```
 
 <Note>
-  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.
 </Note>
 
 ## Keep a copy of every run
@@ -214,7 +215,7 @@
 
 <CardGroup cols={2}>
   <Card title="Tracing" icon="chart-line" href="/agentor/tracing">
     Set up Celesto tracing and learn what each span records.
   </Card>
 
   <Card title="Durable runs" icon="floppy-disk" href="/agentor/durable-runs">

agentor/installation.mdx

@@ -1,20 +1,20 @@
 ---
 title: "Install Agentor and configure LLM providers"
 sidebarTitle: "Installation"
 description: "Install the Agentor Python framework on macOS, Linux, or Windows with pip or uv, pick the optional extras you need, and set up your LLM provider API keys."
 ---
 
 ## Requirements
 
 Before installing Agentor, make sure you have:
 
 * **Python 3.11 or higher** — check your version with `python --version`
 * **pip** or **uv** package manager
 * An API key from your LLM provider (OpenAI, Anthropic, Google, and [many more](/agentor/model-providers))
 
 ## Install from PyPI
 
 Agentor 0.1.0 is a **prerelease**. Ask for it explicitly with `--pre`:
 
 ```bash
 pip install --pre agentor
@@ -76,7 +76,7 @@
 
 ## Set up environment variables
 
 Agentor reads provider credentials from the environment. Create a `.env` file in your project root:
 
 ```bash .env
 # OpenAI (for gpt-4o, gpt-5, etc.)
@@ -93,7 +93,7 @@
 ```
 
 <Note>
   You only need the key for the provider you plan to use. Agentor reaches most providers through their [OpenAI-compatible endpoint](/agentor/model-providers), and the rest through LiteLLM.
 </Note>
 
 ## Load environment variables
@@ -115,7 +115,7 @@
 
 ## Verify installation
 
 Confirm Agentor is installed correctly:
 
 ```python
 import agentor
@@ -131,7 +131,7 @@
 
 ## Enable observability (optional)
 
 To turn on tracing and monitoring, set your Celesto API key:
 
 ```bash
 export CELESTO_API_KEY=your_api_key
@@ -139,22 +139,22 @@
 
 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
 
@@ -164,7 +164,7 @@
   </Card>
 
   <Card title="Model providers" icon="plug" href="/agentor/model-providers">
     Point Agentor at OpenRouter, Groq, Ollama, or any compatible endpoint.
   </Card>
 
   <Card title="Model settings" icon="gear" href="/agentor/api/model-settings">

agentor/tracing.mdx

@@ -1,24 +1,24 @@
 ---
 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
 * Find the slow step, and the expensive one
 * Tell a failed run from one that quietly ran out of turns
 
 <Frame caption="A trace in the Celesto dashboard shows the agent run and tool spans.">
   ![Celesto tracing view with agent run timeline and tool spans](/assets/tracing.png)
 </Frame>
 
 <Note>
-  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.
 </Note>
 
 ***
@@ -27,29 +27,28 @@
 
 <Steps>
   <Step title="Set your Celesto API key">
     Add your Celesto API key to the environment. Get one from the [Celesto dashboard](https://celesto.ai/dashboard).
 
     ```bash
     export CELESTO_API_KEY="cel_..."
     ```
   </Step>
 
-  <Step title="Run an agent">
-    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.
+  <Step title="Turn tracing on">
+    Pass `enable_tracing=True` when building the agent. Every run it makes is then recorded.
 
     ```python
     from agentor import Agentor
 
     agent = Agentor(
         name="Support Agent",
         model="gpt-5-mini",
+        enable_tracing=True,
     )
     result = agent.run("Summarize the latest support tickets.")
     ```
 
-    <Tip>
-      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.
-    </Tip>
+    Agentor raises with a clear message if `enable_tracing=True` is set without `CELESTO_API_KEY`, rather than silently doing nothing.
   </Step>
 
   <Step title="Verify">
@@ -61,6 +60,21 @@
   </Step>
 </Steps>
 
+## 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
@@ -82,7 +96,7 @@
 ## Environment variables
 
 <ParamField path="CELESTO_API_KEY" type="string" required>
   Authenticates trace uploads to Celesto. Holding the key does not by itself
   enable tracing - you also pass `enable_tracing=True` or `tracing=True`.
 </ParamField>
 
@@ -117,7 +131,7 @@
 ```
 
 <ParamField path="endpoint" type="str" required>
   Celesto trace ingest URL.
 </ParamField>
 
 <ParamField path="token" type="str" required>
@@ -128,7 +142,7 @@
   How long to wait for the upload, in seconds.
 </ParamField>
 
-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.
 
 <Note>
   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.
@@ -140,7 +154,7 @@
 
 <AccordionGroup>
   <Accordion title="Traces upload at the end of a run">
     Agentor collects a run's events in memory and posts them once, after the run finishes. There is no background batch worker and nothing to flush before your script exits.
   </Accordion>
 
   <Accordion title="Tracing never breaks a run">
@@ -151,8 +165,20 @@
     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.
   </Accordion>
 
-  <Accordion title="Grouping traces by session is not exposed yet">
-    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.
+  <Accordion title="Group traces by session and attach metadata">
+    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`.
   </Accordion>
 </AccordionGroup>
 
@@ -176,7 +202,7 @@
     * Confirm `CELESTO_API_KEY` is set in the same environment that runs the agent.
     * Confirm you opted in: tracing is off unless you pass `enable_tracing=True`, an explicit `tracer=`, or `tracing=True` on the call.
     * Check no `tracing=False` is being passed on the run.
     * If you use a private deployment, check `CELESTO_BASE_URL` points at your Celesto API.
     * Enable warning logs — a failed upload is reported there rather than raised.
   </Accordion>