When the agent uses one
You don’t have to ask for an Agent by name. Describe the step, and the agent picks the right shape:
The agent tells you which shape it built, and why.
The Agent definition
An Agent’s settings live in a definition file,<name>.agent.md, in the script’s assets/ folder. The file name is the Agent’s name. A block input points at the file, and the block’s card shows the Agent’s name.
Open the definition from the block’s card. It opens as a form; switch to Source to see the file itself.
You can edit the form directly, or ask the agent: “Give the researcher web search and a 10-minute limit”.
What an Agent can do
An Agent acts on its own: nobody sees an action before it happens. Its permission is what keeps it in bounds.- None. The Agent reads and writes only its own working folder. It reaches nothing else.
- Inline permission. Rules written in the definition, such as “read these folders” or “call HubSpot’s read endpoints”.
- A permission file. A
.permission.yamlfile that several Agents can share.
Memory across runs
An Agent keeps a session: its conversation and working folder. The next time the block runs in the same session, the Agent remembers what came before. Use one Agent session per customer, ticket, or thread. The agent sets this up for you when you describe what one conversation is. For a script a trigger runs, the trigger’s Session grouping setting decides which events share a session, and so what the Agent remembers. Without it, every event starts fresh. See Triggers. To see what an Agent did, open its block’s Timeline. It links to the Agent’s session, where you can read the work step by step.While an Agent works
A block that runs an Agent waits for it to finish. The run shows as waiting meanwhile, and the block’s card names the Agent it waits for. If more messages arrive for the same Agent session while it works, the Agent reads them as part of the same task. Stopping the run stops the Agent’s work too. If the Agent runs past its time limit, its work stops and the block reports a timeout.External Agents
An External Agent answers people outside your account through a messaging channel. It’s built from an Agent with a restricted permission, so a hostile message reaches only what that permission allows.An External Agent is different from reaching your own agent over email, Slack, or Telegram. Only you write to your own agent. Anyone who finds an External Agent’s address can write to it.
Where people reach it
How it works
An External Agent is a script with three parts:- A messaging trigger runs the script on each new message.
- The script reads the message, hands it to the Agent, and sends the reply. The script, not the Agent, decides what goes out.
- A restricted Agent reads the message and writes the answer. It’s the only part that reads the sender’s text.
Before you turn it on
- Decide who may write to it. Use the trigger’s sender filter where the channel has one, such as allowed Telegram user IDs, or have the script check the sender.
- Check the permission. Every sender can, in effect, read what the Agent can read.
- Ask for approval where it matters. If the Agent could commit you to something, such as a refund, a booking, or a price, ask the agent to add your approval before the reply goes out. See Approvals and waits.
- Test it. The agent tests the script on a sample message before you enable the trigger. Then send a real message from an account of your own.