Agent Context in Actions

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:

{
  "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:

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.

Get Started

Reference

Agent Context in Actions

Triggers

`event.agent` object

Example: custom claims on agent tokens

​Triggers

​event.agent object

​Example: custom claims on agent tokens

Triggers

`event.agent` object

Example: custom claims on agent tokens