@cursor/july 0.1.4 → 0.1.6

package/docs/example-agents/weather-agent.md

@@ -0,0 +1,302 @@
+---
+title: "Explore the full agentkit surface with a weather agent"
+description: "Trace tools, MCP, channels, approvals, skills, subagents, schedules, hooks, A/B metrics, and evals through one local agent."
+---
+
+# Explore the full agentkit surface with a weather agent
+
+The weather agent is the broadest small example in the repository. It fetches
+live conditions and forecasts, converts units through MCP, writes notes in a
+session workspace, and pauses an alert tool for human approval. The same agent
+also runs from HTTP, Slack, a schedule, and the MCP endpoint.
+
+Use this project when you want to see how agentkit's filesystem pieces fit
+together before you design a larger agent.
+
+[Browse the weather agent source.](../../examples/weather-agent/)
+
+## See every local runtime feature together
+
+Most examples focus on one architecture. Weather agent puts the major local
+runtime features side by side:
+
+| Capability | Source | Role |
+| --- | --- | --- |
+| Root config and instructions | [`agent/agent.ts`](../../examples/weather-agent/agent/agent.ts), [`agent/instructions.md`](../../examples/weather-agent/agent/instructions.md) | Select the local runtime and route each request. |
+| Server tools | [`agent/tools/`](../../examples/weather-agent/agent/tools/) | Fetch Open-Meteo data, call MCP, and model an approval-gated action. |
+| Agent tool | [`save_weather_note.ts`](../../examples/weather-agent/agent/tools/save_weather_note.ts) | Run a Python script inside the session workspace. |
+| Stdio MCP | [`units.ts`](../../examples/weather-agent/agent/mcp-connections/units.ts) | Expose conversion tools to the model, host tools, and channel handlers. |
+| Custom HTTP | [`webhook.ts`](../../examples/weather-agent/agent/channels/webhook.ts) | Start a turn or call MCP without a model turn. |
+| Slack | [`slack.ts`](../../examples/weather-agent/agent/channels/slack.ts), [`slack-app.ts`](../../examples/weather-agent/agent/channels/slack-app.ts) | Compare account-linked chat with a dedicated app offering approval buttons. |
+| Skill and subagent | [`forecast.md`](../../examples/weather-agent/agent/skills/forecast.md), [`researcher/`](../../examples/weather-agent/agent/subagents/researcher/) | Load a procedure on demand or delegate broad research. |
+| Schedule and hook | [`heartbeat.md`](../../examples/weather-agent/agent/schedules/heartbeat.md), [`audit.ts`](../../examples/weather-agent/agent/hooks/audit.ts) | Start recurring task sessions and observe completed turns. |
+| A/B and evals | [`agent/ab.ts`](../../examples/weather-agent/agent/ab.ts), [`evals/`](../../examples/weather-agent/evals/) | Compare a sticky variant and protect tool routing with regression cases. |
+
+## Follow one request
+
+A current-weather question takes this path:
+
+1. The built-in HTTP channel, Slack, or the custom `/report` route creates a
+   durable session.
+2. `instructions.md` tells the model to call `get_weather` instead of
+   guessing.
+3. The server tool geocodes the city, fetches Open-Meteo, validates the
+   response, and returns normalized fields.
+4. The agent writes a short answer. Agentkit records every event in the
+   session stream.
+5. The audit hook observes `turn.completed`. If the session joined the A/B
+   experiment, the collector updates its metrics too.
+
+Forecasts route to `get_forecast`. Unit conversions route to
+`convert_temperature`, which calls the `units` MCP server through
+`ctx.host.mcp`. Climate history and broad comparisons route to the
+`researcher` subagent.
+
+## Prepare the example
+
+You need:
+
+- Node 22.13 or newer.
+- An agent-runtime credential.
+- Network access to Open-Meteo.
+- Python 3 for `save_weather_note`.
+
+The project mounts an account-linked Slack channel. Agentkit checks the
+connection at startup, so sign in even when you plan to call a deterministic
+tool.
+
+The optional approval-enabled Slack app also needs:
+
+```bash
+export WEATHER_AGENT_SLACK_BOT_TOKEN=xoxb-...
+export WEATHER_AGENT_SLACK_APP_TOKEN=xapp-...
+agentkit slack doctor --prefix WEATHER_AGENT
+```
+
+Without those two tokens, the dedicated channel stays idle. The
+account-linked channel still works.
+
+## Inspect before running
+
+```bash
+agentkit validate --dir examples/weather-agent
+agentkit info --dir examples/weather-agent --json
+agentkit eval --dir examples/weather-agent --list
+```
+
+The manifest should report five tools, one skill, one MCP connection, one
+subagent, three authored channels, one schedule, one hook, and one A/B
+experiment. The eval listing should report eight cases.
+
+## Call the typed tools
+
+Start with the current-weather server tool:
+
+```bash
+agentkit call get_weather \
+  --dir examples/weather-agent \
+  --input '{"city":"New York City"}'
+```
+
+`defineTool` gives the input a Zod schema. Agentkit validates the JSON before
+`execute` runs. The result includes the matched place, condition,
+temperature, humidity, wind, gusts, and precipitation.
+
+Try the forecast:
+
+```bash
+agentkit call get_forecast \
+  --dir examples/weather-agent \
+  --input '{"city":"Lisbon","days":5}'
+```
+
+The tool accepts one to seven days. Shared Open-Meteo code lives under
+`agent/lib/`, so agentkit imports it without discovering another tool.
+
+## Compare server and agent execution
+
+Most weather tools use the default `execution: "server"`. Their TypeScript
+runs inside the serve host and can reach `ctx.host` services.
+
+`save_weather_note` uses `execution: "agent"` instead. Agentkit materializes
+its script into the agent environment. The script reads JSON from stdin and
+appends to `weather-notes.md` in that session's workspace:
+
+```bash
+agentkit run --dir examples/weather-agent \
+  --message "Save a note that Boston is cold and windy."
+```
+
+Each session gets its own workspace. Saving a note doesn't edit the authored
+example.
+
+This split matters on cloud. Server tools are local-runtime only. For a cloud
+turn, agentkit includes an agent tool's catalog and script body in the first
+prompt. The cloud model writes and invokes the script in its VM; the serve
+host doesn't materialize it there.
+
+## Use one MCP connection in three places
+
+`agent/mcp-connections/units.ts` starts a local stdio server. The filename
+makes its server name `units`. Agentkit exposes it to:
+
+- the model as MCP tools,
+- server tools through `ctx.host.mcp`, and
+- channel handlers through `host.mcp`.
+
+`convert_temperature` demonstrates the server-tool path:
+
+```bash
+agentkit call convert_temperature \
+  --dir examples/weather-agent \
+  --input '{"value":72,"from":"F"}'
+```
+
+The custom channel demonstrates the handler path. Start the dev server:
+
+```bash
+agentkit dev examples/weather-agent
+```
+
+Then call MCP deterministically through `/convert`:
+
+```bash
+curl -s -X POST \
+  http://127.0.0.1:3000/weather-agent/v1/channels/webhook/convert \
+  -H 'content-type: application/json' \
+  -d '{"value":20,"from":"C"}'
+```
+
+No model chooses a tool in this route. The handler calls the MCP server and
+returns its result.
+
+## Keep conversation state in a custom channel
+
+`POST /report` starts a model turn and waits for it:
+
+```bash
+curl -s -X POST \
+  http://127.0.0.1:3000/weather-agent/v1/channels/webhook/report \
+  -H 'content-type: application/json' \
+  -d '{"message":"What is the weather in Paris?"}'
+```
+
+The response includes a `key`. Send it back on the next request to continue
+the same session:
+
+```bash
+curl -s -X POST \
+  http://127.0.0.1:3000/weather-agent/v1/channels/webhook/report \
+  -H 'content-type: application/json' \
+  -d '{"message":"How about tomorrow?","key":"<key>"}'
+```
+
+This is the custom-channel version of a continuation token. See
+[webhooks and custom channels](../guides/webhooks.md) for route schemas,
+authentication, and asynchronous handlers.
+
+## Pause a tool for human approval
+
+`post_weather_alert` sets `needsApproval: true`. Ask for an ops alert in the
+playground and the model's tool call parks before `execute`:
+
+```bash
+agentkit dev examples/weather-agent
+```
+
+Open the printed playground URL, ask:
+
+> Alert ops that severe weather is approaching Boston.
+
+Approve or deny the call in the transcript. The dedicated Socket Mode Slack
+channel can show the same buttons when `toolApprovals: true` and Slack
+interactivity are configured.
+
+The example tool returns a placeholder success object. It doesn't contact
+Slack, PagerDuty, or an ops board. Replace its `execute` body with your own
+sink before adapting it.
+
+Use a model turn for this proof. A deterministic `agentkit call` runs the
+tool body directly and doesn't demonstrate the parked approval flow.
+
+## Load procedures and delegate research
+
+The forecast skill gives the root agent an on-demand procedure. Agentkit
+advertises the skill's description, then the harness loads its content when
+the request matches.
+
+The `researcher` directory is an SDK subagent. Its description tells the
+parent when to delegate. It inherits the parent's execution surface, but
+gets its own instructions:
+
+```bash
+agentkit run --dir examples/weather-agent \
+  --message "Compare record summer temperatures across Paris, London, and Rome."
+```
+
+Use a skill when the same agent needs a procedure. Use a subagent when the
+parent should hand a bounded task to a specialist. The
+[subagents reference](../reference/subagents.md) explains the current
+inheritance limits.
+
+## Trigger the schedule and inspect the hook
+
+The heartbeat schedule runs at 09:00 UTC on weekdays. Automatic schedule
+timers stay off under `--dev`, so dispatch it manually:
+
+```bash
+curl -s -X POST \
+  http://127.0.0.1:3000/weather-agent/v1/dev/schedules/heartbeat
+```
+
+It creates a task session to check San Francisco, New York, and London.
+The audit hook logs usage after each completed turn. Hooks observe recorded
+events; their failures don't fail the turn.
+
+## Measure variants and regressions
+
+The `weather-tool-efficiency` A/B experiment assigns sessions by a sticky
+hash:
+
+- `control` returns current conditions in Fahrenheit.
+- `treatment` adds a brief Celsius instruction and changes `get_weather` to
+  return Celsius fields.
+
+Samples and aggregate snapshots persist under `.agent-serve/`. The treatment
+only changes current conditions; `get_forecast` still returns Fahrenheit.
+Treat the branch as an example of `ctx.session.abs`, not a complete unit
+policy.
+
+List and run the evals:
+
+```bash
+agentkit eval --dir examples/weather-agent --list
+agentkit eval --dir examples/weather-agent --json
+```
+
+Six cases cover current weather and forecasts against live Open-Meteo. Two
+more cover the local MCP converter and workspace note tool. Together they
+test model routing, external data, host MCP, and agent-side execution.
+
+## Turn the weather tour into your own agent
+
+Keep the architecture and replace the domain:
+
+- Swap Open-Meteo tools for your typed service clients.
+- Keep deterministic transforms behind direct server tools or MCP.
+- Use an agent tool only when code must run in the agent workspace.
+- Gate side effects with `needsApproval`.
+- Put reusable procedures in skills and narrow specialist work into
+  subagents.
+- Add a channel only when the external surface needs its own identity,
+  continuation key, or delivery behavior.
+
+## Where to go next
+
+- [Tools](../reference/tools.md)
+- [MCP connections](../reference/connections.md)
+- [Human-in-the-loop approvals](../guides/human-in-the-loop.md)
+- [Slack](../guides/slack.md)
+- [Schedules and reminders](../reference/schedules.md)
+- [Evals](../evals.md)
+- [Live A/B metrics](../ab.md)