@cursor/july 0.1.111 → 0.1.113

package/dist/docs/guides/agent-to-agent.md

@@ -1,54 +1,32 @@
-# Agent-to-agent
+# Peer agents
 
-Point one agent at another on the same host. The peer keeps its own
-session, instructions, and tools.
+A peer connection lets one agent ask another agent on the same host for
+help. The specialist keeps its own instructions, tools, and session,
+while the caller decides when to delegate and returns the answer to the
+user. Co-host both projects under one `agent-sdk` process.
 
-## Peer or subagent?
-
-Use a [subagent](/docs/reference/subagents.md) to split one job into roles
-inside a single agent. Use a peer when the specialist is a full agent
-you would run on its own.
-
-| | Subagent (`agent/subagents/<id>/`) | Peer (`defineConnection({ agent })`) |
-| --- | --- | --- |
-| Runs as | a child of this agent | an agent on the same host |
-| Tools, MCP connections, sessions | the parent's | its own |
-| Who can reach it | only the parent | other agents, MCP clients, its playground |
-
-## How do I wire two agents?
+## Delegate a question to a specialist
 
-Put both projects in one directory:
-
-```
-agents/
-  concierge/
-    agent/instructions.md
-    agent/mcp-connections/weather.ts
-  weather-agent/
-    agent/instructions.md
-```
-
-`weather-agent` is a normal Agent SDK project. On the concierge, add a
-connection. Set `agent` to the peer's slug, which is its directory
-name:
+Ask the concierge about the weather and it hands the question to the
+specialist. The weather agent answers in its own context, then the
+concierge returns that answer to you.
 
 ```ts
-// agents/concierge/agent/mcp-connections/weather.ts
+// agent/mcp-connections/weather.ts
 import { defineConnection } from "@cursor/july/connections";
 
 export default defineConnection({
   agent: "weather-agent",
-  description: "Delegate weather questions to the weather agent.",
+  description: "Delegate weather questions to the weather specialist.",
 });
 ```
 
-The filename is the MCP server name. The concierge model sees the peer
-under `weather`. See
-[HTTP API](/docs/reference/http-api.md#mcp-endpoint) for the MCP tools.
+Give the concierge a narrow routing rule:
 
-In the concierge `instructions.md`, say when to ask: "When a request
-needs weather, ask the `weather` peer." Scope the line to the work the
-peer should handle. If two agents can ask each other, they will loop.
+```md
+When a request needs current weather, ask the `weather` peer. Return its
+answer.
+```
 
 ```bash
 agent-sdk dev ./agents
@@ -56,15 +34,119 @@ agent-sdk chat --url http://127.0.0.1:3000/concierge \
   --message "What's the weather in Paris right now?"
 ```
 
-Cursor-managed hosting deploys one agent per slug. Keep peers on one
-self-hosted process. Cloud-runtime turns need `--public-url` and
-`--bearer-token`. See [Deployment](/docs/deployment.md).
+The connection filename is the MCP server name the concierge calls, and
+`agent` is the specialist's mount slug, normally its directory name.
+
+## Continue the specialist's session
+
+Ask a follow-up about the same forecast and the specialist picks up
+where it left off, with its own instructions and tool history still in
+place. The first `ask` returns `{ status, sessionId, reply }` as text on
+the `callTool` result. Parse `sessionId` and pass it on the next `ask`
+so the peer remembers its earlier work instead of starting fresh.
+
+```ts
+const first = await ctx.host.mcp.callTool("weather", "ask", {
+  message: "What's the weather in Paris right now?",
+});
+const firstText = first.content.find((part) => part.type === "text");
+if (firstText?.text === undefined) {
+  throw new Error("weather ask returned no text payload");
+}
+const { sessionId } = JSON.parse(firstText.text) as { sessionId: string };
+
+await ctx.host.mcp.callTool("weather", "ask", {
+  message: "How does that compare with tomorrow?",
+  sessionId,
+});
+```
+
+If the specialist is still working, `ask` returns `status: "running"`
+with the session ID, and you can do other work before calling `check`.
+
+```ts
+await ctx.host.mcp.callTool("weather", "check", {
+  sessionId,
+  waitSeconds: 20,
+});
+```
+
+The peer owns this session. Follow-ups stay on the specialist and leave
+the concierge's conversation unchanged.
+
+## Call a deterministic peer tool
+
+You need a forecast for Paris, and the weather agent already has
+`get_forecast`. Host code calls that tool in the specialist's workspace
+and the forecast comes back to the concierge, with no second model turn.
+
+```ts
+const result = await ctx.host.mcp.callTool("weather", "call_tool", {
+  toolName: "get_forecast",
+  input: { city: "Paris" },
+});
+const part = result.content.find((item) => item.type === "text");
+if (part?.text === undefined) {
+  return { ok: false, forecast: null };
+}
+const payload = JSON.parse(part.text) as {
+  isError?: boolean;
+  result?: unknown;
+};
+
+return {
+  ok: result.isError !== true && payload.isError !== true,
+  forecast: payload.result ?? null,
+};
+```
+
+`call_tool` appears only when the peer declares at least one
+deterministic server tool.
+
+## Peer or subagent?
+
+Use a [subagent](/docs/reference/subagents.md) to split one agent's job
+into roles that share its project. Use a peer when the specialist is a
+complete agent you would also run, inspect, or expose on its own.
+
+| | Subagent | Peer |
+| --- | --- | --- |
+| Context | Child role inside one agent | Independent agent and session |
+| Tools and connections | Inherits the parent project | Owns its project surface |
+| Reachability | Parent only | Other co-hosted agents and MCP clients |
+
+## Affinity
+
+Follow-up `ask` and `check` calls resume the same specialist session
+and run as the caller. Those turns show up in the peer's playground;
+only that caller can continue or check the session.
+
+## Practices
+
+- Give each caller a one-way routing rule so agent A cannot send work
+  to B and receive the same request back.
+
+- Prefer `ask` when the specialist should reason. Use `call_tool` when
+  host code already knows which server tool to run.
+
+- Cursor-managed hosting deploys one agent per slug. Use
+  [subagents](/docs/reference/subagents.md) there instead of peer
+  connections.
+
+## Other hosts
+
+Peers need the default multi-agent layout and one shared process;
+unknown slugs and self-references fail at startup.
 
-Unknown slugs and self-references fail `serve` at startup. Peers need
-the default multi-agent layout.
+For a self-hosted caller, expose the shared process with `--public-url`
+and protect it with `--bearer-token`. The
+[Deployment guide](/docs/deployment.md) owns that hosting setup.
 
-## What's next
+## Related
 
-- [MCP connections](/docs/reference/connections.md#peer-mcp-connection): `{ agent }`
+- [MCP connections](/docs/reference/connections.md#peer-mcp-connection):
+  peer configuration and connection naming
+- [MCP endpoint](/docs/reference/http-api.md#mcp-endpoint): exact `ask`,
+  `check`, and `call_tool` schemas
 - [Subagents](/docs/reference/subagents.md): specialists inside one agent
-- [HTTP API](/docs/reference/http-api.md#mcp-endpoint): `/v1/mcp`
+- [Deployment](/docs/deployment.md): secure shared-host setup