Worked examples

How agents, tools, connectors, and skills compose in practice.

Sample 1 — Scheduling a meeting

This one example uses all four entities. An "Executive Assistant" agent books a meeting on the user's real calendar.

The pieces

The agent

---
name: exec-assistant
description: Schedules meetings and protects focus time.
model: default
tools:
  - calendar          # connector — delegated, writes are approval-gated
  - current_time      # built-in tool
skills:
  - schedule-meeting  # the playbook
---

# Role
You are an executive assistant. Book meetings on the user's behalf and always
confirm the proposed slot before creating anything.

The skill

---
name: schedule-meeting
description: Find a slot that works and book it, without double-booking.
allowed_tools:        # subset of the agent's tools
  - calendar
  - current_time
---

# Procedure
1. `current_time` to anchor relative dates in the user's timezone.
2. `calendar` / `find_free_time` across the requested window.
3. Confirm the proposed slot with the user.
4. `calendar` / `create_event` once they agree.

The run

User: "Set up a 30-minute sync with Bob next Tuesday afternoon."

1. The executor assembles the tool registry

   From the declaration it builds: the built-in current_time, the calendar connector tool (exposing list_events, find_free_time, create_event), and — because a skill is attached — load_skill. Nothing else is callable this run.

2. The agent loads the playbook

   It sees schedule-meeting in the skill index and calls load_skill to pull in the procedure. Now it knows the order of operations and the house rules.

3. Resolve the date tool

   current_time returns today's date in the user's timezone, so "next Tuesday afternoon" becomes a concrete ISO window — no guessing.

4. Find a slot connector · read

   calendar / find_free_time. The executor resolves this user's OAuth token at call time and sends only that. Being a read, it runs immediately and returns the earliest free 30-minute gap.

5. Confirm with the user

   The agent proposes the slot. (If it needed more detail it could park the run with ask_user.)

6. Book it connector · write

   calendar / create_event is tagged write, so under supervised autonomy the run parks for approval instead of firing. The user approves in the inbox (or from Slack), the run resumes, and the event is created as them, exactly once.

What each layer contributed

• Agent — granted exactly two tools, carried the user's identity, and enforced the approval policy.
• Tool — current_time removed a whole class of date errors.
• Connector — reached a real SaaS calendar as the user, with the write gated.
• Skill — encoded the "confirm before booking, never double-book" procedure once, reusable by any agent granting the same tools.

Throughout, governance was uniform: DLP on what went to and came back from the model, the user's own credential only, an approval on the write, and every step on the run's event stream for replay and audit.

Sample 2 — A weekly metrics report

The same composition, with a skill that ships code instead of just instructions.

---
name: metrics-reporter
model: strong
tools:
  - web_search
  - code_execution
  - current_time
skills:
  - weekly-report
knowledge:
  - product-analytics-docs
---

The run:

• search_knowledge (switched on by knowledge:) pulls the metric definitions, returning citations so the numbers are traceable.
• web_search fills in any external benchmark.
• run_skill_script (switched on by skills:) runs the skill's charting entrypoint in the sandbox; the PDF it writes comes back as a downloadable artifact, rendered inline in chat.
• Nothing parks — every tool here is a read, so the whole run completes unattended.

Want it every Monday? Attach an automation with a cron trigger. The same agent runs through the same execution path, and the report lands in the inbox (or a Slack DM) without anyone asking.

Choosing where logic belongs