Action guide
Record the concrete state change your agent made
POST
/v1/events · agent.action_takenEmit a domain event with `actor.type` set to 'agent' for the actual change your agent performed (file.deleted, invoice.refunded, project.archived). This is the audit-grade record customers and auditors will look at first when something is disputed.
When to emit
After the agent-orchestrated tool has actually mutated state (database write committed, third party API confirmed). Same place a human-triggered version of the action would log.
Example payload
await recalled.events.create({
action: "agent.action_taken",
actor: { id: user.id, email: user.email },
organization: user.organizationId,
metadata: {
triggered_by_user: "value",
conversation_id: "value",
tool_call_id: "value"
},
});Metadata to include
Keep metadata flat and consistent across your service so it plays well with search and CSV exports.
| Key | Purpose |
|---|---|
triggered_by_user | User id of the human who started the conversation that led here |
conversation_id | Conversation id, for replay |
tool_call_id | tool_call_id this action came out of |
model | Agent model id |
confidence | Optional confidence label, low / medium / high |
reasoning | Short reason the agent took this action |
result | success or failure |
Suggested retention
Keep for at least 12 months. This is the audit-grade record of what your agent actually did to user data.