Agents

An agent is a reusable definition: a persona with instructions and tools. Configure it once, then trigger runs as often as you need.

The API resource was previously named "teammates". /api/v2/teammates and client.teammates remain permanent aliases.

Create an agent

Key fields

All fields

Field	Type	Description
role	string	Optional persona role
goals	string	Optional goals injected into prompt context
email_inbox	bool	Enable email inbox at creation. Returns email_address immediately
webhook	bool	Enable webhook trigger at creation. Returns webhook_url once
allowed_senders	string[]	Allowed addresses or @domain patterns for email triggers
inbound_imessage_enabled	bool	Enable inbound Apple Messages routing for this agent
imessage_chat_guid	string	BlueBubbles chat GUID used to route inbound iMessage and send replies
enable_self_improvement	bool	Weekly review-and-improve task. See Self-improvement

Trigger runs

An agent can be triggered four ways: a direct message, inbound email, inbound iMessage, or webhook. Direct runs inherit the agent's default_permission_mode unless the run overrides permission_mode.

Message

Streams by default too; see Runs for the event loop.

Email inbox

Webhook

The webhook URL is shown once, at creation or when calling enable_webhook(); it cannot be retrieved again. Calling enable_webhook() again rotates it.

Apple Messages (BlueBubbles), not self-serve yet

iMessage triggers aren't generally available to API developers yet. Dedicated per-app numbers exist today as a setup we do with you (see iMessage Inbox). For production, prefer email or webhooks for now.

Python

Requires BlueBubbles on your account. Use a dedicated 1:1 chat unless everyone in that thread should trigger the agent and receive its replies.

Self-improvement

Set enable_self_improvement=True and the agent gets better at its job on its own: once a week it reviews its recent runs and, where it finds a clear, durable problem, rewrites its own instructions, reshapes its tasks, and records lessons for next time.

How the weekly review behaves

• It only changes things when the runs warrant it. A good week means no changes.
• Reversible edits apply on their own; higher-stakes moves (disabling a task, connecting an integration) are surfaced for a human to approve, not done automatically.
• Enabling it also turns on the task-setup, history, and memory tools the review needs.
• It runs as a normal scheduled task on the agent, so it's billed like any other run.
• With end-user scoping, each end-user's agent only reviews and learns from that end-user's own runs.

Manage agents

Documents

Agents maintain persistent documents across runs: polished deliverables like latest-report, as opposed to per-run files. Read them via the API (writing stays with the agent):

Next: Runs · Tasks · Models · Tools