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

# Agent Context in Actions

> Access agent identity and metadata in Auth0 Actions using the `event.agent` object.

> [!WARNING]
>
> **The Agent as Principal feature is in .**

When a request involves an agent-linked client, the Actions runtime exposes an `event.agent` object. The object is absent when no agent is involved, so existing Actions code is unaffected.

## Triggers

`event.agent` is present in the following triggers:

| Trigger | When `event.agent` is present |
| - | - |
| `credentials-exchange` | Client credentials grant where the client has `agent_id` set. |
| `post-login` | Authorization code, token exchange, or device flow where the client has `agent_id` set. |

## `event.agent` object

The `event.agent` object has the following schema:

```json theme={null}
{
  "agent_id": "agt_72jbvv7LfRKYp59gtRLtkn",
  "agent_metadata": {
    "env": "prod"
  }
}
```

`event.client` is unchanged; it continues to reflect the linked OAuth client that authenticated the request.

## Example: custom claims on agent tokens

Use `event.agent` in a `credentials-exchange` Action to add agent context to access tokens:

```javascript theme={null}
exports.onExecuteCredentialsExchange = async (event, api) => {
  if (event.agent) {
    api.accessToken.setCustomClaim('agent_env', event.agent.agent_metadata?.env);
    api.accessToken.setCustomClaim('agent_id', event.agent.agent_id);
  }
};
```

To learn more about writing Actions, read [Write Your First Action](https://auth0.com/docs/customize/actions/write-your-first-action.md).