Overview
Agents
Section titled “Agents”An agent is saved instructions and configuration that Lucy runs
without a person in the chat: when someone presses Run, when another
system calls its webhook, or on a schedule. Each run is a
conversation, answered like any other (tools, files, steps), so it
can be followed live (…/messages/{messageId}/events) and read
afterwards; AgentRun sums it up (status, output, usage).
Identity (AgentIdentity): an owner agent acts as the person who
made it, with their access; its runs are their conversations and
they can continue one as themselves. A service agent (only
org_admins create one) is its own principal: its runs are read-only,
visible to org_admins only.
Connections: an agent has its own, never its owner’s. Its managers
sign in at a service for it (startAgentConnection): the same
account as their own, or another one such as a shared mailbox, with
its own token, revocable on its own. Each tool of its connections is
allow or deny for it (setAgentToolPermission), within the
organization’s permission: nobody is there to answer ask, so a tool
the organization asks for is denied to agents. Runs never get tools
on people’s computers (local). The audit log shows the agent as the
actor of what its runs do.
Triggers: a webhook (POST to its webhook_url, which carries the
trigger’s token) or a schedule (5-field cron in an IANA time zone,
at most every 15 minutes). Either can POST the result to a
callback URL, signed with the trigger’s token (AgentCallback).
One run at a time per agent: manual and webhook runs queue behind
the one in progress (at most 20 queued); a schedule that fires while
a run is going records a skipped run. Each run has budgets
(limits), and its cost counts against the owner’s quotas (owner)
or the agent’s own (service: quota subject type agent, else the
organization’s default per member), and the organization’s monthly
budget.
The organization decides who may use agents (settings.agents, off
until an admin turns it on).