Tools

Enable tools for a project

When creating a project (or in Settings → Tools), turn on Tools and select which tools your agent needs (e.g. Gmail, Google Calendar, Slack, HubSpot). The platform will require you to connect an account for each selected tool before runs can use it.

Tools are per-project. The same dashboard user can have different connections per project (e.g. different Gmail accounts).

Connect your accounts

In the project Settings → Tools tab, you'll see each enabled tool and its connection status. Click Connect to start the OAuth flow (e.g. sign in with Google for Gmail/Calendar). After authorizing, the connection is stored and used when your agent runs.

If a connection expires (e.g. token revoked), the UI will show Expired — Reconnect. Click to go through OAuth again. You can Disconnect to remove the connection.

Use tools in your agent

In your agent function, use ctx.tools.<slug>.<action>(...). The platform injects the right credentials at runtime. Example for Gmail:

with ctx.safe_step("read_inbox"):
    result = ctx.tools.gmail.read_inbox(max_results=5, query="is:inbox")
    emails = result.get("messages", [])

with ctx.commit_step("send_email", description="Send digest"):
    ctx.tools.gmail.send_email(to="user@example.com", subject="Digest", body=digest)

Tool slugs match the names in the UI (e.g. gmail, google_calendar, slack). Each tool exposes actions (e.g. read_inbox, send_email).

Tool approvals

By default, approval is required before the platform runs certain tool actions (e.g. sending email, posting to Slack, creating calendar events). When your agent hits such an action inside a commit_step, the run pauses and you see an approval request in the dashboard.

Actions that require approval by default:

• Gmail: send_email, reply, draft
• Google Calendar: create_event, update_event, delete_event
• Google Sheets: append_row, update_cells, create_sheet
• Slack: post_message, reply_in_thread
• HubSpot: create_contact, update_contact, create_deal, update_deal, create_task, log_activity

Approval context (preview)

When a tool action needs approval, the dashboard shows what will happen (e.g. email to, subject, body preview). You can provide this context explicitly by passing preview in commit_step(), or you can omit it — the platform will automatically build the context from the first tool call inside the step.

If you see two step cards (e.g. send_digest and tool:gmail:send_email), ensure your agent image uses an SDK that sends the deferred step name so the approval is attached to your single commit step.

Missing or expired connections

If you trigger a run and a required tool is not connected or has expired, the run can fail with a clear error. Fix it by going to Settings → Tools and connecting or reconnecting the account.

agent.yaml (optional)

You can list tools in your repo's agent.yaml under tools: (e.g. [gmail]). The platform uses this to pre-select tools when creating the project; you still need to connect accounts in the dashboard after deploy.