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

# Decorators

> Reference for the @agent, @chain, and @tool decorators that auto-instrument your code.

Three decorators cover the vast majority of instrumentation needs. Each captures inputs and outputs, measures duration, and emits `*_start` and `*_end` events to Observatory.

***

## `@agent`

The top-level decorator. Wrap the function that handles one user request.

```python theme={"dark"}
from flowxobservatory import agent

@agent("claims-approval")
def run(ctx, payload):
    # business logic
    return result
```

### Parameters

**name** `string` *required*

The agent identifier. Shows up in the **Agent** column on LLM Calls, in Risk Dashboard, and in ROI baselines. Use kebab-case.

**user\_id** `string`

Identifier of the user this run belongs to. Surfaces in filters and Threads grouping.

**user\_props** `dict`

Arbitrary user properties attached to the run (e.g. `{"plan": "enterprise"}`).

**tags** `list[str]`

Tags attached to every run of this agent (e.g. `["claims", "prod"]`). Used for filtering in LLM Calls and analytics.

***

## `@chain`

Use for sub-steps that aren't external work but are worth seeing in the trace.

```python theme={"dark"}
from flowxobservatory import chain

@chain("extract-claim-data")
def extract(payload):
    return {"holder": payload["policy_id"], ...}
```

### Parameters

Same shape as `@agent`. The chain inherits the parent run's app and project context — you only need to name it.

> [!TIP]
>
> If you're using LangChain or LangGraph, the callback handler creates chain spans automatically. Use `@chain` for handwritten Python that lives between LangChain calls or for non-LangChain frameworks.

***

## `@tool`

Use for the leaf-level units of work — database queries, REST calls, file operations, computation.

```python theme={"dark"}
from flowxobservatory import tool

@tool("lookup_policy_holder")
def lookup_policy_holder(policy_id):
    return db.fetch(policy_id)
```

### Parameters

Same signature as `@agent` — `name`, `user_id`, `user_props`, `tags`.

***

## Async functions

All three decorators detect `async def` and wrap it natively. No different syntax.

```python theme={"dark"}
@agent("claims-approval")
async def run(ctx, payload):
    data = await extract(payload)
    return await decide(data)
```

***

## Error handling

If the wrapped function raises, the SDK:

1. Emits an `*_end` event with `status=error` and the exception's class and message.
2. Re-raises the exception unchanged.

Your error handling does not need to change. Observatory captures the error context; your `try/except` still runs.

***

## Class-based instrumentation

The decorators also work on methods. Use `@agent` on the entry method of a class:

```python theme={"dark"}
class ClaimsAgent:
    @agent("claims-approval")
    def run(self, ctx, payload):
        ...
```

`self` is excluded from captured inputs automatically.

***

## When NOT to use a decorator

| Situation | Better choice |
| - | - |
| You want to attach a custom event (`saved`, `chat`) | Call `track_event()` directly. |
| The function runs millions of times per request | Decorate the parent, not the leaf. |
| You only want to record success metrics | Use the analytics API on the recorded run instead. |

***

## Related resources

> [card] [Event reporting](https://docs.flowx.ai/6.x/observatory/sdk/event-reporting.md)
>
> Custom events and the wire protocol.

> [card] [SDK overview](https://docs.flowx.ai/6.x/observatory/sdk/overview.md)
>
> Install and configuration.


## Related topics

- [Event reporting](https://docs.flowx.ai/6.x/observatory/sdk/event-reporting.md)
- [SDK overview](https://docs.flowx.ai/6.x/observatory/sdk/overview.md)
- [Getting started](https://docs.flowx.ai/6.x/observatory/getting-started.md)
- [Custom component](https://docs.flowx.ai/6.x/docs/building-blocks/ui-designer/ui-component-types/root-components/custom.md)
- [Observatory](https://docs.flowx.ai/6.x/observatory/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.