@cursor/july 0.1.1

package/dist/docs/assets/quickstart.md.tVPiGK_L.js

@@ -0,0 +1,35 @@
+import{_ as a,c as i,o as e,ag as t}from"./chunks/framework.CAZyNGu9.js";const c=JSON.parse('{"title":"Build your first weather agent","description":"Create a weather agent, add a typed tool, run it from the terminal, and open it in the playground.","frontmatter":{"title":"Build your first weather agent","description":"Create a weather agent, add a typed tool, run it from the terminal, and open it in the playground."},"headers":[],"relativePath":"quickstart.md","filePath":"quickstart.md"}'),n={name:"quickstart.md"};function h(l,s,p,r,o,d){return e(),i("div",null,[...s[0]||(s[0]=[t(`<h1 id="build-your-first-weather-agent" tabindex="-1">Build your first weather agent <a class="header-anchor" href="#build-your-first-weather-agent" aria-label="Permalink to &quot;Build your first weather agent&quot;">​</a></h1><p>Create an agent, give it a weather tool, run a complete turn, and chat with it in the browser.</p><h2 id="prerequisites" tabindex="-1">Prerequisites <a class="header-anchor" href="#prerequisites" aria-label="Permalink to &quot;Prerequisites&quot;">​</a></h2><p>You need:</p><ul><li>Node 22.13 or newer. Bun isn&#39;t supported.</li><li>The <code>agentkit</code> CLI. See <a href="./README.html#run-the-cli">Run the CLI</a> for the current package and command names.</li><li>A Cursor credential for model turns. Sign in once:</li></ul><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> login</span></span></code></pre></div><p>You can also set <code>CURSOR_API_KEY</code> instead of signing in.</p><h2 id="scaffolding-agents" tabindex="-1">Scaffolding Agents <a class="header-anchor" href="#scaffolding-agents" aria-label="Permalink to &quot;Scaffolding Agents&quot;">​</a></h2><p>Have Cursor read <a href="./../skills/create-agent/SKILL.html"><code>skills/create-agent/SKILL.md</code></a> and describe what you want:</p><blockquote><p>Build me a weather agent for the playground. Start with one weather tool and guide me through the remaining decisions.</p></blockquote><p>Cursor asks for missing choices, shows you the plan, then builds and verifies the agent. Continue below to do the same by hand.</p><p>See <a href="./scaffolding-agents.html">Scaffold an agent with Cursor</a> for the full guided workflow.</p><h2 id="create-your-project" tabindex="-1">Create your project <a class="header-anchor" href="#create-your-project" aria-label="Permalink to &quot;Create your project&quot;">​</a></h2><p>Start with the built-in scaffold:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> init</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./weather-agent</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">cd</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> weather-agent</span></span></code></pre></div><p>The scaffold creates the files agentkit discovers:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>weather-agent/</span></span>
+<span class="line"><span>├── agent/</span></span>
+<span class="line"><span>│   ├── agent.ts</span></span>
+<span class="line"><span>│   ├── instructions.md</span></span>
+<span class="line"><span>│   └── tools/</span></span>
+<span class="line"><span>│       └── echo.ts</span></span>
+<span class="line"><span>└── package.json</span></span></code></pre></div><p><code>agent.ts</code> holds the model and runtime settings. <code>instructions.md</code> is the always-on system prompt. Each file under <code>agent/tools/</code> becomes a tool.</p><p>Check the project before you run it:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> validate</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> info</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span></span></code></pre></div><p>These commands inspect the project without starting a model turn.</p><h2 id="run-your-agent" tabindex="-1">Run your agent <a class="header-anchor" href="#run-your-agent" aria-label="Permalink to &quot;Run your agent&quot;">​</a></h2><p>The scaffold already works. Run one turn from the terminal:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --message</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;Introduce yourself in one sentence.&quot;</span></span></code></pre></div><p><code>run</code> starts the agent, sends the message, and waits for the final reply. It prints a JSON trajectory with the response, tool calls, and token usage. It also writes an NDJSON trace under <code>.agentkit/traces/</code>.</p><h2 id="add-weather-instructions" tabindex="-1">Add weather instructions <a class="header-anchor" href="#add-weather-instructions" aria-label="Permalink to &quot;Add weather instructions&quot;">​</a></h2><p>Replace <code>agent/instructions.md</code>:</p><div class="language-md vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">md</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;"># Weather agent</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">You are a concise weather assistant.</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Use </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\`get_weather\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> before answering questions about current weather.</span></span>
+<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Tell the user the weather data is simulated.</span></span>
+<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">-</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Keep replies to two sentences or fewer.</span></span></code></pre></div><p>Remove the demo echo tool:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">rm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> agent/tools/echo.ts</span></span></code></pre></div><h2 id="add-a-weather-tool" tabindex="-1">Add a weather tool <a class="header-anchor" href="#add-a-weather-tool" aria-label="Permalink to &quot;Add a weather tool&quot;">​</a></h2><p>Create <code>agent/tools/get_weather.ts</code>:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineTool } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@anysphere/agentkit/tools&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { z } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;zod&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Get simulated current weather for a city.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  inputSchema: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">object</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    city: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">().</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">describe</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;City name, such as San Francisco&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">),</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  }),</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  async</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> execute</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">city</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> temperatureF</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Math.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">round</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(Math.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">random</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">*</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">90</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> -</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 32</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">+</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 32</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      city,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      temperatureF,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      conditions: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;sunny&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    };</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>The file adds one tool named <code>get_weather</code>:</p><ul><li><code>description</code> tells the model when to call it.</li><li><code>inputSchema</code> defines and validates the arguments.</li><li><code>execute</code> runs on the server and returns data to the model.</li></ul><p>This version uses simulated data so you can run it without another API key. Replace <code>execute</code> with a weather API when you&#39;re ready.</p><h2 id="try-the-weather-tool" tabindex="-1">Try the weather tool <a class="header-anchor" href="#try-the-weather-tool" aria-label="Permalink to &quot;Try the weather tool&quot;">​</a></h2><p>Call the tool directly first:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> call</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> get_weather</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --input</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;city&quot;:&quot;San Francisco&quot;}&#39;</span></span></code></pre></div><p><code>call</code> validates the input and runs <code>execute</code> without a model turn. If the result looks right, ask the agent:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --message</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;What&#39;s the weather in San Francisco?&quot;</span></span></code></pre></div><p>The agent calls <code>get_weather</code>, receives the result, and uses it in the final reply. agentkit runs the tool loop for you.</p><h2 id="open-the-playground" tabindex="-1">Open the playground <a class="header-anchor" href="#open-the-playground" aria-label="Permalink to &quot;Open the playground&quot;">​</a></h2><p>Start the development server:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> serve</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dev</span></span></code></pre></div><p>Open the playground URL printed in the terminal. Ask the same weather question. The playground streams the reply and shows the tool arguments and result inline.</p><h2 id="where-to-go-next" tabindex="-1">Where to go next <a class="header-anchor" href="#where-to-go-next" aria-label="Permalink to &quot;Where to go next&quot;">​</a></h2><ul><li><a href="./reference/tools.html">Tools</a>: add more typed capabilities, like replacing the simulated weather tool with live Open-Meteo data</li><li><a href="./evals.html">Evals</a>: turn this weather question into a regression check</li><li><a href="./reference/channels.html">Channels</a>: expose the agent through HTTP, Slack, or another webhook</li><li><a href="./building-with-agents.html">Building agents with agents</a>: have a coding agent extend the project for you</li></ul>`,48)])])}const g=a(n,[["render",h]]);export{c as __pageData,g as default};

package/dist/docs/assets/quickstart.md.tVPiGK_L.lean.js

@@ -0,0 +1 @@
+import{_ as a,c as i,o as e,ag as t}from"./chunks/framework.CAZyNGu9.js";const c=JSON.parse('{"title":"Build your first weather agent","description":"Create a weather agent, add a typed tool, run it from the terminal, and open it in the playground.","frontmatter":{"title":"Build your first weather agent","description":"Create a weather agent, add a typed tool, run it from the terminal, and open it in the playground."},"headers":[],"relativePath":"quickstart.md","filePath":"quickstart.md"}'),n={name:"quickstart.md"};function h(l,s,p,r,o,d){return e(),i("div",null,[...s[0]||(s[0]=[t("",48)])])}const g=a(n,[["render",h]]);export{c as __pageData,g as default};

package/dist/docs/assets/reference_agent-config.md.Bpd7HQwf.js

@@ -0,0 +1,34 @@
+import{_ as e,c as i,o as a,ag as t}from"./chunks/framework.CAZyNGu9.js";const k=JSON.parse('{"title":"Agent config","description":"defineAgent at agent/agent.ts: the model, the local and cloud runtimes, and serving programmatically.","frontmatter":{"title":"Agent config","description":"defineAgent at agent/agent.ts: the model, the local and cloud runtimes, and serving programmatically."},"headers":[],"relativePath":"reference/agent-config.md","filePath":"reference/agent-config.md"}'),n={name:"reference/agent-config.md"};function o(l,s,h,d,r,p){return a(),i("div",null,[...s[0]||(s[0]=[t(`<h1 id="agent-config-agent-agent-ts" tabindex="-1">Agent config (<code>agent/agent.ts</code>) <a class="header-anchor" href="#agent-config-agent-agent-ts" aria-label="Permalink to &quot;Agent config (\`agent/agent.ts\`)&quot;">​</a></h1><p><code>agent/agent.ts</code> default-exports <code>defineAgent(config)</code>: which model runs the agent, where turns execute, and runtime-specific defaults. Everything is optional on the root agent.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineAgent } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@anysphere/agentkit&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineAgent</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  model: {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    id: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;grok-4.5&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    params: [</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      { id: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;effort&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, value: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;high&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      { id: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;fast&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, value: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;true&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    ],</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  }, </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// optional; this is the default</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  runtime: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;local&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// default, or &quot;cloud&quot;</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // cloud: {</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  //   repos: [{ url: &quot;https://github.com/org/repo&quot;, startingRef: &quot;main&quot; }],</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // },</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // local: { cwd: &quot;../harness&quot; },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="fields-on-defineagent" tabindex="-1">Fields on <code>defineAgent</code> <a class="header-anchor" href="#fields-on-defineagent" aria-label="Permalink to &quot;Fields on \`defineAgent\`&quot;">​</a></h2><p><code>defineAgent</code> accepts these fields.</p><table tabindex="0"><thead><tr><th>Field</th><th>Type</th><th>Meaning</th></tr></thead><tbody><tr><td><code>model</code></td><td>string or <code>{ id, params }</code></td><td>Cursor model for turns. Defaults to <code>grok-4.5</code> with <code>effort=high</code>, <code>fast=true</code> on the root agent. Subagents omit it to inherit.</td></tr><tr><td><code>name</code></td><td>string</td><td>Display name override. Defaults to the package name or directory name.</td></tr><tr><td><code>description</code></td><td>string</td><td>What the agent is for. Required on subagents; the parent model reads it to decide when to delegate. Documentation-only on the root.</td></tr><tr><td><code>instructions</code></td><td>string</td><td>Inline instructions. Prefer <code>instructions.md</code>; this exists for subagents and generated configs.</td></tr><tr><td><code>runtime</code></td><td><code>&quot;local&quot;</code> or <code>&quot;cloud&quot;</code></td><td>Where turns execute. Default <code>&quot;local&quot;</code>.</td></tr><tr><td><code>cloud</code></td><td>object</td><td>Cloud agent defaults: repos, env, envVars, forwarded to the Cursor SDK. Used when <code>runtime</code> is <code>&quot;cloud&quot;</code>, and as the base merged under per-session <code>cloud</code> send options.</td></tr><tr><td><code>local</code></td><td><code>{ cwd? }</code></td><td>Local harness defaults; ignored for cloud turns.</td></tr></tbody></table><h2 id="choose-a-model" tabindex="-1">Choose a model <a class="header-anchor" href="#choose-a-model" aria-label="Permalink to &quot;Choose a model&quot;">​</a></h2><p><code>model</code> is a Cursor model id string, or <code>{ id, params }</code>. Effort and speed are params, not id suffixes. The SDK rejects suffix-style ids like <code>grok-4.5-fast</code>:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">model</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  id</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;grok-4.5&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  params</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    { id: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;effort&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, value: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;high&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    { id: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;fast&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, value: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;true&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  ],</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>A plain string works when you don&#39;t need params:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">model</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;composer-2.5&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span></code></pre></div><h2 id="choose-a-runtime" tabindex="-1">Choose a runtime <a class="header-anchor" href="#choose-a-runtime" aria-label="Permalink to &quot;Choose a runtime&quot;">​</a></h2><p><code>runtime: &quot;local&quot;</code> (the default) runs turns on the Cursor SDK harness on this machine. The session id doubles as the SDK agent id, and server tools, skills, sandbox seeds, and tool approvals all apply.</p><p><code>runtime: &quot;cloud&quot;</code> runs turns on Cursor cloud agents (<code>bc-…</code> ids). Pass a <code>cloud</code> block with the repos the VM carries. In-process server tools are not available, and instructions and agent-tool catalogs are prepended to the first prompt, because the local session workspace is not the cloud VM.</p><p><code>validate</code> warns when <code>runtime: &quot;cloud&quot;</code> is combined with server tools, skills, or sandbox seeds that only apply locally. The full capability matrix and the patterns that hold up are in the <a href="./../guides/cloud-runtime.html">Cloud runtime guide</a>.</p><h2 id="local-cwd" tabindex="-1">Local cwd <a class="header-anchor" href="#local-cwd" aria-label="Permalink to &quot;Local cwd&quot;">​</a></h2><p><code>local.cwd</code> sets the default parent directory for local harness workspaces. Each session uses <code>&lt;cwd&gt;/&lt;sessionId&gt;</code> (absolute, or relative to the project root) unless a per-send <code>workspaceDir</code> overrides it.</p><p>This is your control over ambient context. Session workspaces are real Cursor project directories, so the harness loads <code>AGENTS.md</code> and <code>.cursor</code> config from ancestor directories. An agent inside a big monorepo that must not inherit the monorepo&#39;s rules points <code>cwd</code> outside it (or runs with <code>--state-root</code> under <code>/tmp</code>). An agent that <em>needs</em> a specific checkout&#39;s skills and rules points <code>cwd</code> inside that checkout.</p><h2 id="the-cloud-block" tabindex="-1">The <code>cloud</code> block <a class="header-anchor" href="#the-cloud-block" aria-label="Permalink to &quot;The \`cloud\` block&quot;">​</a></h2><p>Cloud agent defaults forwarded to the Cursor SDK: <code>repos</code> (each <code>{ url, startingRef? }</code>), environment selection, <code>envVars</code>, and the rest. A local agent uses the same block as the base config when a channel opens a cloud-attached session per send. That hybrid pattern is covered in <a href="./../guides/cloud-runtime.html#hybrid-local-agent-cloud-sessions">Cloud runtime</a>.</p><h2 id="generate-instructions" tabindex="-1">Generate instructions <a class="header-anchor" href="#generate-instructions" aria-label="Permalink to &quot;Generate instructions&quot;">​</a></h2><p>When the system prompt must be computed, author <code>agent/instructions.ts</code> instead of markdown:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineInstructions } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@anysphere/agentkit&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineInstructions</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  markdown: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`You are the on-call assistant for \${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">process</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">env</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">TEAM_NAME</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}.\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>The directory form and the runtime mapping are in <a href="./instructions.html">Instructions</a>.</p><h2 id="serve-programmatically" tabindex="-1">Serve programmatically <a class="header-anchor" href="#serve-programmatically" aria-label="Permalink to &quot;Serve programmatically&quot;">​</a></h2><p><code>serve(dirOrProject, options)</code> embeds the server in your own process:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { serve } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@anysphere/agentkit&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> handle</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> serve</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;./my-agent&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  port: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">3000</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  apiKey: process.env.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">CURSOR_API_KEY</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// optional; see credential order</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">console.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">log</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`listening on \${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">handle</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">url</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// handle.callTool(...), handle.dispatchSchedule(&quot;heartbeat&quot;),</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// handle.createReminder(...), handle.project, await handle.close()</span></span></code></pre></div><p><code>ServeOptions</code> mirrors the CLI flags: <code>port</code>, <code>host</code>, <code>dev</code>, <code>stateRoot</code>, <code>apiKey</code>, <code>schedules</code>, <code>reminders</code>, <code>playground</code>, <code>authToken</code> (the <code>--bearer-token</code> equivalent), <code>allowAnonymous</code>, <code>publicUrl</code>, <code>cursorEvents</code>, and <code>mode: &quot;single&quot; | &quot;multi&quot;</code>. The Cursor credential resolves in one order everywhere: explicit <code>apiKey</code>, then <code>CURSOR_API_KEY</code>, then the key stored by <code>agentkit login</code>.</p><h2 id="what-s-next" tabindex="-1">What&#39;s next <a class="header-anchor" href="#what-s-next" aria-label="Permalink to &quot;What&#39;s next&quot;">​</a></h2><p>Continue with these pages:</p><ul><li><a href="./instructions.html">Instructions</a>: the required half of a minimal agent</li><li><a href="./../guides/cloud-runtime.html">Cloud runtime</a>: when and how to leave the host</li><li><a href="./cli.html">CLI</a>: the flags <code>ServeOptions</code> mirrors</li></ul>`,31)])])}const g=e(n,[["render",o]]);export{k as __pageData,g as default};

package/dist/docs/assets/reference_agent-config.md.Bpd7HQwf.lean.js

@@ -0,0 +1 @@
+import{_ as e,c as i,o as a,ag as t}from"./chunks/framework.CAZyNGu9.js";const k=JSON.parse('{"title":"Agent config","description":"defineAgent at agent/agent.ts: the model, the local and cloud runtimes, and serving programmatically.","frontmatter":{"title":"Agent config","description":"defineAgent at agent/agent.ts: the model, the local and cloud runtimes, and serving programmatically."},"headers":[],"relativePath":"reference/agent-config.md","filePath":"reference/agent-config.md"}'),n={name:"reference/agent-config.md"};function o(l,s,h,d,r,p){return a(),i("div",null,[...s[0]||(s[0]=[t("",31)])])}const g=e(n,[["render",o]]);export{k as __pageData,g as default};

package/dist/docs/assets/reference_channels.md.D7JTR03W.js

@@ -0,0 +1,53 @@
+import{_ as e,c as a,o as i,ag as t}from"./chunks/framework.CAZyNGu9.js";const c=JSON.parse('{"title":"Channels","description":"The authoring reference for defineChannel, the built-in HTTP channel, route schemas, handler args, and the auth policies.","frontmatter":{"title":"Channels","description":"The authoring reference for defineChannel, the built-in HTTP channel, route schemas, handler args, and the auth policies."},"headers":[],"relativePath":"reference/channels.md","filePath":"reference/channels.md"}'),n={name:"reference/channels.md"};function h(l,s,o,d,r,p){return i(),a("div",null,[...s[0]||(s[0]=[t(`<h1 id="channels" tabindex="-1">Channels <a class="header-anchor" href="#channels" aria-label="Permalink to &quot;Channels&quot;">​</a></h1><p>A channel is the surface an agent lives on. The built-in HTTP session channel is always mounted. Custom channels declare their own routes under <code>/v1/channels/&lt;id&gt;</code>. The Slack and GitHub packs are prebuilt channels with platform transports. This page is the authoring reference; for the walkthrough, see the <a href="./../guides/webhooks.html">Webhooks guide</a>.</p><h2 id="the-built-in-http-channel" tabindex="-1">The built-in HTTP channel <a class="header-anchor" href="#the-built-in-http-channel" aria-label="Permalink to &quot;The built-in HTTP channel&quot;">​</a></h2><p>It&#39;s always mounted, under <code>/&lt;slug&gt;</code> in the default multi-agent layout: session create, follow-up, stream, stop, the sessions list, approvals, deterministic tool calls, health, and info. For the route-by-route contract, see the <a href="./http-api.html">HTTP API reference</a>.</p><p>Author <code>agent/channels/http.ts</code> only to override its defaults:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  bearerAuth,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  httpChannel,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  localDevStrict,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">} </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@anysphere/agentkit/channels&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> httpChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  auth: [</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">localDevStrict</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(), </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">bearerAuth</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(process.env.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">AGENT_TOKEN</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ??</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)],</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  onMessage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">message</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, { </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">auth</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span></span>
+<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">    \`[caller \${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">auth</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">?.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">principalId</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ??</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;anonymous&quot;}] \${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">message</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="define-a-custom-channel" tabindex="-1">Define a custom channel <a class="header-anchor" href="#define-a-custom-channel" aria-label="Permalink to &quot;Define a custom channel&quot;">​</a></h2><p>Author <code>agent/channels/&lt;id&gt;.ts</code>. The filename is the channel id and the route prefix:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineChannel, POST } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@anysphere/agentkit/channels&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { z } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;zod&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  routes: [</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">    POST</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;/review&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Review a pull request on this channel&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      bodySchema: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">object</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        message: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(),</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        prUrl: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">().</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">url</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(),</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        thread: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">().</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">optional</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(),</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      }),</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">      handler</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">async</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">_req</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, { </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">callTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">send</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">body</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">        const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> prepared</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> callTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;inspect_pr&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">          prUrl: body.prUrl,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        });</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">        if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (prepared.isError) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">          return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Response.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">json</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">            { error: prepared.errorMessage </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">??</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;Could not inspect pull request&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">            { status: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">502</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">          );</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        }</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">        const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> session</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> send</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
+<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">          \`\${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">body</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">message</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\n\\n</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">Read pr.json before answering.\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">          {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">            continuationToken: body.thread </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">??</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> \`pr:\${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">body</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">prUrl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">            workspaceFiles: {</span></span>
+<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">              &quot;pr.json&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">JSON</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">stringify</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(prepared.result, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">2</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">??</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;null&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">            },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">          }</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        );</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">        return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Response.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">json</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ sessionId: session.id });</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    }),</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  ],</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  events: {</span></span>
+<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">    &quot;message.completed&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">event</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">channel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">      // deliver the reply to the surface that owns this channel</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // auth: [...], state: {...}, onStart(...), onStop(...)</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>This example assumes <code>agent/tools/inspect_pr.ts</code> exists. The handler calls it before the model turn, so every review starts with validated PR data. It also derives a stable conversation key from the PR URL and writes the tool result to <code>pr.json</code>. Instructions can ask the model to inspect a PR, but host code guarantees it.</p><h2 id="route-verbs-and-schemas" tabindex="-1">Route verbs and schemas <a class="header-anchor" href="#route-verbs-and-schemas" aria-label="Permalink to &quot;Route verbs and schemas&quot;">​</a></h2><p><code>GET</code>, <code>POST</code>, <code>PUT</code>, <code>PATCH</code>, and <code>DELETE</code> helpers build routes. Their schemas are Zod, enforced at compile time:</p><table tabindex="0"><thead><tr><th>Verb</th><th>Required schema</th></tr></thead><tbody><tr><td><code>GET</code></td><td><code>querySchema</code></td></tr><tr><td><code>POST</code> / <code>PUT</code> / <code>PATCH</code></td><td><code>bodySchema</code> (optional <code>querySchema</code>)</td></tr><tr><td><code>DELETE</code></td><td>both optional</td></tr></tbody></table><p>Plain JSON Schema objects won&#39;t type-check; use <code>z.object({})</code> or <code>z.unknown()</code> for intentionally open surfaces. The host validates before the handler runs. Handlers receive typed <code>args.body</code> and <code>args.query</code>, and empty POST bodies are coerced to <code>{}</code> first. Declared schemas are projected on <code>GET /v1/info</code>, which powers the playground&#39;s <strong>Try</strong> buttons and composer <strong>slash commands</strong>.</p><h2 id="handler-arguments" tabindex="-1">Handler arguments <a class="header-anchor" href="#handler-arguments" aria-label="Permalink to &quot;Handler arguments&quot;">​</a></h2><p>Handlers receive the Fetch <code>Request</code> and an args object:</p><table tabindex="0"><thead><tr><th>Member</th><th>What it is</th></tr></thead><tbody><tr><td><code>send(message, options?)</code></td><td>Run a model turn on this channel; returns the session handle. Options: <code>continuationToken</code> (the conversation key), <code>workspaceFiles</code>, <code>workspaceDir</code>, <code>cloud</code> (attach cloud repos for this session), <code>auth</code> (defaults to the request principal), <code>sdkAgentId</code> (resume a specific SDK agent).</td></tr><tr><td><code>getSession(sessionId)</code></td><td>Look up an existing session on this channel</td></tr><tr><td><code>receive(channelDefinition, input)</code></td><td>Hand off to another channel (schedules use this)</td></tr><tr><td><code>callTool(name, input, options?)</code></td><td>Deterministic server-tool call (<a href="./tools.html#call-a-tool-without-a-model-turn">Tools</a>)</td></tr><tr><td><code>body</code>, <code>query</code>, <code>params</code></td><td>Validated payloads and <code>:param</code> path segments</td></tr><tr><td><code>auth</code></td><td>The <code>AuthContext</code> resolved by this route&#39;s auth chain</td></tr><tr><td><code>requestIp</code></td><td>The TCP peer address</td></tr><tr><td><code>host</code></td><td>Shared services: <code>host.mcp</code>, <code>host.github</code>, <code>host.slack</code>, <code>host.reminders</code></td></tr><tr><td><code>waitUntil(promise)</code></td><td>Background work that outlives the response</td></tr><tr><td><code>sessionUrls(request, sessionId)</code></td><td>Absolute playground + trace URLs for a session on this mount</td></tr></tbody></table><h2 id="events" tabindex="-1">Events <a class="header-anchor" href="#events" aria-label="Permalink to &quot;Events&quot;">​</a></h2><p>The <code>events</code> map subscribes the channel to stream events for the sessions it owns. Keys are event types from the <a href="./sessions.html#the-event-vocabulary">event vocabulary</a>, or <code>&quot;*&quot;</code>. Handlers receive <code>(event, channel, ctx)</code>, where <code>channel.state</code> is the per-session adapter state and <code>ctx</code> exposes session info and host services. This is where a channel delivers replies back to its surface.</p><h2 id="state-and-lifecycle" tabindex="-1">State and lifecycle <a class="header-anchor" href="#state-and-lifecycle" aria-label="Permalink to &quot;State and lifecycle&quot;">​</a></h2><p><code>state</code> declares the starting per-session adapter state (JSON), persisted on the session record. Routes and event handlers read and mutate it through <code>channel.state</code>. <code>onStart(args)</code> runs when the channel mounts. It receives <code>send</code>, <code>receive</code>, <code>callTool</code>, <code>host</code>, and friends; the Slack pack opens its Socket Mode connection here. <code>onStop()</code> runs when the server drains.</p><h2 id="auth-policies" tabindex="-1">Auth policies <a class="header-anchor" href="#auth-policies" aria-label="Permalink to &quot;Auth policies&quot;">​</a></h2><p>Every route runs an auth-policy chain: the channel&#39;s <code>auth</code> array, or <code>[localDevStrict()]</code> when unset. A policy is a function <code>(request, info) =&gt; AuthContext | null</code> (async allowed); the first non-null wins, and a request no policy admits gets <code>401</code>.</p><table tabindex="0"><thead><tr><th>Policy</th><th>Admits</th></tr></thead><tbody><tr><td><code>localDevStrict()</code></td><td>Direct loopback callers with no proxy-forwarding headers (<code>X-Forwarded-For</code>, <code>X-Real-IP</code>, <code>Forwarded</code>, and <code>X-Forwarded-Host</code> are all rejected, so tunnels and same-host reverse proxies don&#39;t silently re-expose the route), plus a loopback <code>Host</code> header, which rejects DNS-rebinding callers that reach 127.0.0.1 with a remote hostname.</td></tr><tr><td><code>localDev()</code></td><td>Like <code>localDevStrict()</code> but without the <code>Host</code> check. An explicit, weaker opt-in.</td></tr><tr><td><code>loopbackOnly()</code></td><td>A loopback TCP peer, ignoring forwarding headers; for dev relays that legitimately carry them, like <code>gh webhook forward</code>.</td></tr><tr><td><code>bearerAuth(token)</code></td><td><code>Authorization: Bearer &lt;token&gt;</code>, compared in constant time. Also accepts a verifier function mapping a presented token to an <code>AuthContext</code>.</td></tr><tr><td><code>allowAll()</code></td><td>Everyone, as an <code>anonymous</code> principal. Only for surfaces protected upstream (an HMAC-verified webhook) or intentionally public.</td></tr></tbody></table><p>The resolved <code>AuthContext</code> (<code>{ authenticator, principalId, principalType, attributes? }</code>) becomes the request principal. Sessions bind to the principal that created them, and follow-up, stream, and list routes enforce ownership (<code>403</code> otherwise).</p><p>Server flags interact with authored auth: <code>--bearer-token</code> swaps the default <code>localDevStrict()</code> for <code>bearerAuth(...)</code> on channels that don&#39;t author their own chain, and <code>--allow-anonymous</code> swaps it for <code>allowAll()</code>. Authored <code>auth</code> arrays always win over both. A channel that declares <code>[localDevStrict()]</code> stays loopback-only even on an <code>--allow-anonymous</code> host.</p><h2 id="first-class-channels" tabindex="-1">First class channels <a class="header-anchor" href="#first-class-channels" aria-label="Permalink to &quot;First class channels&quot;">​</a></h2><p><strong>Slack</strong> (<code>@anysphere/agentkit/channels/slack</code>): Socket Mode transport, streaming replies, engagement rules, approval cards. Author <code>agent/channels/slack.ts</code> with <code>slackChannel()</code>. Guide: <a href="./../guides/slack.html">Slack</a>.</p><p><strong>GitHub</strong> (<code>@anysphere/agentkit/channels/github</code>): webhook dispatch with signature verification, per-event hooks returning <code>{ auth }</code> (a model turn), <code>{ task }</code> (host work), or <code>null</code>, and CLI tooling for replay and live forwarding. Author <code>agent/channels/github.ts</code> with <code>githubChannel()</code>. Guide: <a href="./../guides/github.html">GitHub</a>.</p><p>For other platforms like Discord or Teams, use the authored <code>defineChannel</code> webhook form.</p><h2 id="continuation-semantics" tabindex="-1">Continuation semantics <a class="header-anchor" href="#continuation-semantics" aria-label="Permalink to &quot;Continuation semantics&quot;">​</a></h2><p>Channels own their continuation-token format. The built-in HTTP channel mints opaque rotating tokens, Slack uses <code>channelId:threadTs</code>, and PR automations use keys like <code>pr:owner/repo#N</code>. Same token, same durable session; one active continuation per session; the HTTP channel returns <code>409</code> for stale tokens. For the full session model, see <a href="./sessions.html">Sessions</a>.</p><h2 id="what-s-next" tabindex="-1">What&#39;s next <a class="header-anchor" href="#what-s-next" aria-label="Permalink to &quot;What&#39;s next&quot;">​</a></h2><p>Continue with these pages:</p><ul><li><a href="./../guides/webhooks.html">Webhooks guide</a>: the same API, walked through</li><li><a href="./http-api.html">HTTP API</a>: the built-in routes precisely</li><li><a href="./sessions.html">Sessions and streaming</a>: the events channels subscribe to</li></ul>`,35)])])}const E=e(n,[["render",h]]);export{c as __pageData,E as default};

package/dist/docs/assets/reference_channels.md.D7JTR03W.lean.js

@@ -0,0 +1 @@
+import{_ as e,c as a,o as i,ag as t}from"./chunks/framework.CAZyNGu9.js";const c=JSON.parse('{"title":"Channels","description":"The authoring reference for defineChannel, the built-in HTTP channel, route schemas, handler args, and the auth policies.","frontmatter":{"title":"Channels","description":"The authoring reference for defineChannel, the built-in HTTP channel, route schemas, handler args, and the auth policies."},"headers":[],"relativePath":"reference/channels.md","filePath":"reference/channels.md"}'),n={name:"reference/channels.md"};function h(l,s,o,d,r,p){return i(),a("div",null,[...s[0]||(s[0]=[t("",35)])])}const E=e(n,[["render",h]]);export{c as __pageData,E as default};

package/dist/docs/assets/reference_cli.md.DA730zCu.js

@@ -0,0 +1,33 @@
+import{_ as i,c as a,o as t,ag as e}from"./chunks/framework.CAZyNGu9.js";const c=JSON.parse('{"title":"CLI","description":"Every agentkit command and the flags that matter, from serve and run to the slack and github packs.","frontmatter":{"title":"CLI","description":"Every agentkit command and the flags that matter, from serve and run to the slack and github packs."},"headers":[],"relativePath":"reference/cli.md","filePath":"reference/cli.md"}'),n={name:"reference/cli.md"};function h(l,s,d,k,r,p){return t(),a("div",null,[...s[0]||(s[0]=[e(`<h1 id="cli-reference" tabindex="-1">CLI reference <a class="header-anchor" href="#cli-reference" aria-label="Permalink to &quot;CLI reference&quot;">​</a></h1><p>Run the CLI with Node 22.13+. <code>agentkit help</code> prints the built-in summary, and most commands print their own usage when a required argument is missing.</p><table tabindex="0"><thead><tr><th>Command</th><th>Description</th></tr></thead><tbody><tr><td><a href="#serve"><code>serve</code></a></td><td>Serve agents over HTTP (multi-agent by default)</td></tr><tr><td><a href="#chat"><code>chat</code></a></td><td>Talk to a running server from the terminal</td></tr><tr><td><a href="#run"><code>run</code></a></td><td>One-shot turn on an ephemeral server; JSON trajectory</td></tr><tr><td><a href="#call"><code>call</code></a></td><td>Call a server tool directly, no model turn</td></tr><tr><td><a href="#eval"><code>eval</code></a></td><td>Run filesystem evals</td></tr><tr><td><a href="#trajectory"><code>trajectory</code></a></td><td>Summarize a saved events.ndjson</td></tr><tr><td><a href="#init"><code>init</code></a></td><td>Scaffold a project (or print the setup guide)</td></tr><tr><td><a href="#info"><code>info</code></a></td><td>Print the discovered agent surface</td></tr><tr><td><a href="#validate"><code>validate</code></a></td><td>Check the project; non-zero exit on errors</td></tr><tr><td><a href="#login--logout--whoami"><code>login</code> / <code>logout</code> / <code>whoami</code></a></td><td>Manage the host&#39;s Cursor credential</td></tr><tr><td><a href="#slack"><code>slack …</code></a></td><td>Slack pack: init, manifests, doctor</td></tr><tr><td><a href="#github"><code>github …</code></a></td><td>GitHub pack: forward, replay, events, doctor</td></tr></tbody></table><p>The flags shared across commands: <code>--dir &lt;path&gt;</code> (project root, default <code>.</code>), <code>--json</code> (machine output where supported), <code>--url &lt;baseUrl&gt;</code> (target a running server instead of starting one), <code>--bearer-token</code> (require it on <code>serve</code>; send it from <code>chat</code>, <code>run</code>, <code>eval</code>, and <code>call</code>), and <code>--state-root &lt;path&gt;</code> (durable state directory, default <code>&lt;dir&gt;/.agentkit</code>).</p><h2 id="serve" tabindex="-1">serve <a class="header-anchor" href="#serve" aria-label="Permalink to &quot;serve&quot;">​</a></h2><p><code>serve</code> hosts every agent under a directory, multi-agent by default.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> serve</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--dir </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pat</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">h</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--port </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">3000]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--host </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">127.0.0.1]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--dev]</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">                  [--mode multi</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">|</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">single] [--api-key </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">key</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">                  [--state-root </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">path</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--bearer-token </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">secret</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> |</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> --allow-anonymous]</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">                  [--public-url </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">url</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--no-schedules] [--no-playground]</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">                  [--no-docs] [--cursor-events --repo owner/name]</span></span></code></pre></div><p>Serves every agent under <code>--dir</code>. A directory that is itself an agent project mounts under its directory name; a directory of projects mounts each child. The index lives at <code>/</code>, each agent at <code>/&lt;slug&gt;/v1/*</code> and <code>/&lt;slug&gt;/playground</code>. On a TTY, press Enter to restart; it reloads agent code.</p><table tabindex="0"><thead><tr><th>Flag</th><th>Meaning</th></tr></thead><tbody><tr><td><code>--dev</code></td><td>Dev mode. Schedules and reminders never auto-fire (dispatch through <code>/v1/dev/...</code>), the playground session list widens (loopback), GitHub channels accept unsigned loopback deliveries, and Vite HMR starts when the toolchain is present.</td></tr><tr><td><code>--mode</code></td><td><code>multi</code> (default: slugged routes plus an index) or <code>single</code> (one agent at the unslugged <code>/v1/*</code>).</td></tr><tr><td><code>--api-key</code></td><td>Cursor API key. Falls back to <code>CURSOR_API_KEY</code>, then the stored <code>login</code> credential.</td></tr><tr><td><code>--bearer-token</code></td><td>Require this bearer token on API routes; replaces the loopback-only default on channels without authored auth. Mutually exclusive with <code>--allow-anonymous</code>.</td></tr><tr><td><code>--allow-anonymous</code></td><td>Admit every HTTP caller as one <code>anonymous</code> principal. Trusted networks only.</td></tr><tr><td><code>--public-url</code></td><td>The base URL where this host is reachable from outside. Required for peer MCP connections on cloud-runtime turns.</td></tr><tr><td><code>--no-schedules</code></td><td>Disable the cron runner outside dev mode.</td></tr><tr><td><code>--no-playground</code></td><td>Skip the web playground (and its auto-build / HMR).</td></tr><tr><td><code>--no-docs</code></td><td>Skip the documentation site at <code>/docs</code> (and its auto-build).</td></tr><tr><td><code>--cursor-events</code></td><td>Pull SCM webhook events from Cursor&#39;s <code>/v0/scm-events</code> instead of receiving webhooks. Requires a signed-in host and <code>--repo</code> (repeatable). Offset state lives under <code>&lt;state-root&gt;/cursor-events/</code>.</td></tr></tbody></table><h2 id="chat" tabindex="-1">chat <a class="header-anchor" href="#chat" aria-label="Permalink to &quot;chat&quot;">​</a></h2><p><code>chat</code> talks to a running server from the terminal.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> chat</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --url</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">            # interactive REPL</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> chat</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --url</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> …</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --message</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;Is the PR ready to approve?&quot;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">       # one-shot</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> chat</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --url</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> …</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --message</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;hello&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --json</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">              # JSON trajectory</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> chat</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --url</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> https://host</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --bearer-token</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$TOKEN</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    # authed server</span></span></code></pre></div><p>Streams the reply live: text, tool calls, and a per-turn usage footer. <code>--json</code> requires <code>--message</code> and prints <code>{ ok, sessionId, continuationToken, trajectory }</code>. <code>--text</code> prints a compact dump, and <code>--no-color</code> forces plain output.</p><h2 id="run" tabindex="-1">run <a class="header-anchor" href="#run" aria-label="Permalink to &quot;run&quot;">​</a></h2><p><code>run</code> executes one turn on an ephemeral server and prints a JSON trajectory.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --message</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;Is https://github.com/acme/checkout/pull/42 ready?&quot;</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --message</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;first&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --message</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;then this&quot;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">   # multi-turn</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --url</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --message</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;…&quot;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # running server</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --message</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;…&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --events</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> /tmp/run.ndjson</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    # custom trace path</span></span></code></pre></div><p>The create-and-test loop in one command: start an ephemeral server (port 0, temp state root outside the project), send the message(s), print a JSON trajectory, and write an NDJSON trace (default <code>&lt;dir&gt;/.agentkit/traces/&lt;sessionId&gt;.ndjson</code>). Progress streams to stderr on a TTY.</p><table tabindex="0"><thead><tr><th>Flag</th><th>Meaning</th></tr></thead><tbody><tr><td><code>--message</code></td><td>The user message; repeatable for multi-turn. <code>--messages-file</code> takes a JSON array of strings.</td></tr><tr><td><code>--session</code> / <code>--continuation-token</code></td><td>Follow up an existing session on a running server.</td></tr><tr><td><code>--events &lt;file&gt;</code> / <code>--no-events</code></td><td>Override the trace path, or skip the trace.</td></tr><tr><td><code>--text</code></td><td>Compact text output instead of JSON.</td></tr><tr><td><code>--timeout-ms</code></td><td>Abort a hung turn.</td></tr><tr><td><code>--no-stream</code></td><td>Silence live progress on stderr.</td></tr><tr><td><code>--slug</code></td><td>Pick one agent when <code>--dir</code> mounts several.</td></tr></tbody></table><h2 id="call" tabindex="-1">call <a class="header-anchor" href="#call" aria-label="Permalink to &quot;call&quot;">​</a></h2><p><code>call</code> invokes a server tool directly, with no model turn.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> call</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> inspect_pr</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
+<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --input</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;prUrl&quot;:&quot;https://github.com/acme/checkout/pull/42&quot;}&#39;</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> call</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> inspect_pr</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --url</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --input</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{…}&#39;</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> call</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> inspect_pr</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --input</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{…}&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --session</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ses_…</span></span></code></pre></div><p>Deterministic server-tool invocation through <code>POST /v1/tools/:toolName</code>: schema-validated, in-process, no model turn, no API key. <code>--session</code> runs it inside an existing session and records it on that session&#39;s stream (serializing with model turns). See <a href="./tools.html#call-a-tool-without-a-model-turn">Tools</a>.</p><h2 id="eval" tabindex="-1">eval <a class="header-anchor" href="#eval" aria-label="Permalink to &quot;eval&quot;">​</a></h2><p><code>eval</code> runs the project&#39;s filesystem evals.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --list</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">          # discovered datapoints</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">                 # run all</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> builds/checkout</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # one datapoint</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> builds</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">          # every datapoint in the file</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --tag</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> smoke</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">     # by tag (repeatable)</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --json</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">          # machine-readable results</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --verbose</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">       # stream t.log lines + reply snippets</span></span></code></pre></div><p>Runs <code>evals/**/*.eval.{ts,js}</code> on an ephemeral server, or against <code>--url</code>. Select by exact case id, file id (a prefix), several of either, tags, or nothing for all. See <a href="./../evals.html">Evals</a>.</p><h2 id="trajectory" tabindex="-1">trajectory <a class="header-anchor" href="#trajectory" aria-label="Permalink to &quot;trajectory&quot;">​</a></h2><p><code>trajectory</code> summarizes a saved event stream.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> trajectory</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --events</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> /tmp/run.ndjson</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--text]</span></span></code></pre></div><p>Turns any saved NDJSON event stream into the same trajectory JSON <code>run</code> prints.</p><h2 id="init" tabindex="-1">init <a class="header-anchor" href="#init" aria-label="Permalink to &quot;init&quot;">​</a></h2><p><code>init</code> scaffolds a new project.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> init</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./my-agent</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">   # scaffold package.json + agent/ + a demo tool</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> init</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">              # no directory: print the setup guide</span></span></code></pre></div><p>Refuses to overwrite existing files.</p><h2 id="info" tabindex="-1">info <a class="header-anchor" href="#info" aria-label="Permalink to &quot;info&quot;">​</a></h2><p><code>info</code> prints the discovered agent surface.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> info</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--json]</span></span></code></pre></div><p>The discovered surface: model, instructions size, tools, skills, MCP connections, subagents, channels and their routes, schedules, hooks, and diagnostics. <code>--json</code> matches <code>GET /v1/info</code>; with multiple agents it prints one entry per slug.</p><h2 id="validate" tabindex="-1">validate <a class="header-anchor" href="#validate" aria-label="Permalink to &quot;validate&quot;">​</a></h2><p><code>validate</code> checks the project and sets the exit code.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> validate</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span></span></code></pre></div><p>Prints diagnostics per agent and exits non-zero when any has error-severity diagnostics (<code>serve</code> refuses to start in that state). Warnings (cloud runtime combined with local-only capabilities, say) print without failing it.</p><h2 id="login-logout-whoami" tabindex="-1">login / logout / whoami <a class="header-anchor" href="#login-logout-whoami" aria-label="Permalink to &quot;login / logout / whoami&quot;">​</a></h2><p>Three commands manage the host&#39;s Cursor credential.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> login</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--api-key </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">ke</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">y</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--key-name </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">nam</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> whoami</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--json]</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> logout</span></span></code></pre></div><p><code>login</code> signs the host in to Cursor: browser sign-in mints a named, dashboard-revocable API key, and only the key is stored (the default name is <code>agentkit (&lt;hostname&gt;)</code>). It powers inference, the cloud runtime, and Cursor account MCP connections. <code>whoami</code> shows which credential is active and why: explicit flag, then <code>CURSOR_API_KEY</code>, then the stored login. <code>logout</code> removes the stored key.</p><p>Non-production backends: login and account RPCs honor <code>CURSOR_API_BASE_URL</code> while the SDK harness honors <code>CURSOR_BACKEND_URL</code>. Set both to the same URL, or keys minted on one backend are rejected by the other.</p><h2 id="slack" tabindex="-1">slack <a class="header-anchor" href="#slack" aria-label="Permalink to &quot;slack&quot;">​</a></h2><p>The <code>slack</code> subcommands generate and verify the Slack side of a channel.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> slack</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> setup</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">                              # guided checklist</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> slack</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> init</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --name</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;My Agent&quot;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">     # channel + manifests + env.example</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> slack</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> init</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --no-prefix</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">           # shared SLACK_* vars</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> slack</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> init</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --channel-posts</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">       # + message.channels/groups events</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> slack</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> manifest</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --env</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dev</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">|</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">prod</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">|</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">both</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">       # regenerate manifests</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> slack</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> doctor</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --prefix</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> MY_AGENT</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">           # token / connectivity checks</span></span></code></pre></div><p>See the <a href="./../guides/slack.html">Slack guide</a>.</p><h2 id="github" tabindex="-1">github <a class="header-anchor" href="#github" aria-label="Permalink to &quot;github&quot;">​</a></h2><p>The <code>github</code> subcommands test webhook channels against real repositories.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> github</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> doctor</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--install]                </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># gh + cli/gh-webhook extension</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> github</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> events</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--json]           </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># per-agent URL + event list</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> github</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> forward</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--repo </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">owner/repo</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> |</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> --org</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ORG]</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> github</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> replay</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pr-url</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">|</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">owner/repo#N</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt; </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">--dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    [--events a,b,c</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">|</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;*&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--action …] [--conclusion …] [--comment …]</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    [--context …] [--secret …] [--dry-run] [--out DIR]</span></span></code></pre></div><p><code>forward</code> wraps <code>gh webhook forward</code>: repo admin required, and blank any env <code>GITHUB_TOKEN</code> / <code>GH_TOKEN</code> or deliveries 401. <code>replay</code> synthesizes GitHub-shaped payloads from read access only, the deterministic tier. <code>--slug</code> and <code>--channel</code> target one agent among several. See the <a href="./../guides/github.html">GitHub guide</a>.</p><h2 id="environment-variables" tabindex="-1">Environment variables <a class="header-anchor" href="#environment-variables" aria-label="Permalink to &quot;Environment variables&quot;">​</a></h2><p>These are the most common environment variables the CLI and the channel packs read.</p><table tabindex="0"><thead><tr><th>Variable</th><th>Meaning</th></tr></thead><tbody><tr><td><code>CURSOR_API_KEY</code></td><td>The Cursor credential, checked after <code>--api-key</code> and before the stored login</td></tr><tr><td><code>GITHUB_APP_ID</code> / <code>GITHUB_APP_PRIVATE_KEY</code> / <code>GITHUB_APP_INSTALLATION_ID</code></td><td>GitHub App auth for outbound API calls</td></tr><tr><td><code>GITHUB_TOKEN</code> / <code>GH_TOKEN</code></td><td>Token auth for outbound API calls; must be blank for <code>github forward</code></td></tr><tr><td><code>SLACK_BOT_TOKEN</code> / <code>SLACK_APP_TOKEN</code></td><td>Slack tokens (single-agent); <code>&lt;PREFIX&gt;_SLACK_*</code> per agent otherwise</td></tr></tbody></table>`,58)])])}const g=i(n,[["render",h]]);export{c as __pageData,g as default};

package/dist/docs/assets/reference_cli.md.DA730zCu.lean.js

@@ -0,0 +1 @@
+import{_ as i,c as a,o as t,ag as e}from"./chunks/framework.CAZyNGu9.js";const c=JSON.parse('{"title":"CLI","description":"Every agentkit command and the flags that matter, from serve and run to the slack and github packs.","frontmatter":{"title":"CLI","description":"Every agentkit command and the flags that matter, from serve and run to the slack and github packs."},"headers":[],"relativePath":"reference/cli.md","filePath":"reference/cli.md"}'),n={name:"reference/cli.md"};function h(l,s,d,k,r,p){return t(),a("div",null,[...s[0]||(s[0]=[e("",58)])])}const g=i(n,[["render",h]]);export{c as __pageData,g as default};

package/dist/docs/assets/reference_connections.md.C3vNH_DE.js

@@ -0,0 +1,26 @@
+import{_ as i,c as e,o as a,ag as n}from"./chunks/framework.CAZyNGu9.js";const d=JSON.parse(`{"title":"MCP Connections","description":"Pull in tools from MCP servers: remote, stdio, the signed-in Cursor account's connectors, and peer agents.","frontmatter":{"title":"MCP Connections","description":"Pull in tools from MCP servers: remote, stdio, the signed-in Cursor account's connectors, and peer agents."},"headers":[],"relativePath":"reference/connections.md","filePath":"reference/connections.md"}`),t={name:"reference/connections.md"};function h(l,s,o,p,r,c){return a(),e("div",null,[...s[0]||(s[0]=[n(`<h1 id="mcp-connections" tabindex="-1">MCP Connections <a class="header-anchor" href="#mcp-connections" aria-label="Permalink to &quot;MCP Connections&quot;">​</a></h1><p>An MCP connection gives the agent tools from an MCP server. One file per server under <code>agent/mcp-connections/</code>, and the filename becomes the server name the model sees. An MCP connection default-exports <code>defineConnection</code> from <code>@anysphere/agentkit/connections</code>, and the transport comes in four shapes: remote HTTP, local stdio, the signed-in Cursor account&#39;s connectors, and peer agents on the same host.</p><h2 id="remote-mcp-server" tabindex="-1">Remote MCP server <a class="header-anchor" href="#remote-mcp-server" aria-label="Permalink to &quot;Remote MCP server&quot;">​</a></h2><p>Point an MCP connection at a remote server with a URL.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineConnection } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@anysphere/agentkit/connections&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  url: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://mcp.linear.app/mcp&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  headers: { authorization: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`Bearer \${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">process</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">env</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">LINEAR_TOKEN</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Tokens come from env vars. Never hardcode them in the file.</p><h2 id="local-stdio-mcp-server" tabindex="-1">Local stdio MCP server <a class="header-anchor" href="#local-stdio-mcp-server" aria-label="Permalink to &quot;Local stdio MCP server&quot;">​</a></h2><p>Run a local MCP server as a child process with <code>command</code>.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  command: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;node&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  args: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;--import&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;tsx&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;mcp/units-server.ts&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // env, cwd</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>This suits small purpose-built servers, like a <code>units</code> converter shipped next to the agent.</p><h2 id="cursor-account-mcp-connection" tabindex="-1">Cursor account MCP connection <a class="header-anchor" href="#cursor-account-mcp-connection" aria-label="Permalink to &quot;Cursor account MCP connection&quot;">​</a></h2><p><code>{ cursorAccount: true }</code> exposes the MCP connectors the signed-in Cursor account already authorized (dashboard → MCP): Linear, Notion, Slack, and the rest, without any token configuration. Every tool executes on the Cursor backend with the account&#39;s stored OAuth credentials, so raw tokens never reach the serve host, session workspaces, or traces.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// agent/mcp-connections/cursor.ts</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ cursorAccount: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, servers: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Linear&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] });</span></span></code></pre></div><p>The host must be signed in (<code>agentkit login</code> or <code>CURSOR_API_KEY</code>); <code>serve</code> fails fast at startup otherwise, and logs each connector&#39;s live status (<code>connected</code>, <code>needsAuth</code>, <code>error</code>) as it starts. The optional <code>servers</code> list restricts which connectors are exposed.</p><p>Local turns and host-side calls go through a loopback bridge guarded by a per-startup secret. Cloud-runtime turns reach the same bridge through the serve <code>--public-url</code>, so <code>servers</code> filters apply there too. A cloud-capable agent that combines a <code>servers</code> filter with no <code>--public-url</code> fails at startup rather than running unfiltered. Backend execution covers the account&#39;s HTTP/SSE servers. Stdio servers can&#39;t run server-side, so author a <code>{ command }</code> MCP connection for those.</p><div class="caution custom-block github-alert"><p class="custom-block-title">CAUTION</p><p>Whoever can talk to the agent can drive these connectors, because they are ordinary agent tools. <code>serve</code> refuses to start when <code>--allow-anonymous</code> is combined with account MCP connections. Prefer <code>--bearer-token</code> on shared hosts.</p></div><h2 id="peer-mcp-connection" tabindex="-1">Peer MCP connection <a class="header-anchor" href="#peer-mcp-connection" aria-label="Permalink to &quot;Peer MCP connection&quot;">​</a></h2><p><code>{ agent: &quot;&lt;slug&gt;&quot; }</code> addresses another agent mounted on the same serve host. The model gets the peer&#39;s <code>ask</code> and <code>check</code> (and <code>call_tool</code>) tools and can delegate work to it:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  agent: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;weather-agent&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Delegate weather questions to the weather agent.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Unknown slugs and self-references fail <code>serve</code> at startup. Resolution (loopback versus <code>--public-url</code>), loop caveats, and the delegation model are in the <a href="./../guides/agent-to-agent.html">Agent-to-agent guide</a>.</p><h2 id="every-mcp-connection-is-available-in-three-places" tabindex="-1">Every MCP connection is available in three places <a class="header-anchor" href="#every-mcp-connection-is-available-in-three-places" aria-label="Permalink to &quot;Every MCP connection is available in three places&quot;">​</a></h2><p>One authored MCP connection serves three consumers.</p><ol><li><p><strong>Cursor agent:</strong> Local or cloud turns see the MCP connection through SDK <code>mcpServers</code>, and the model calls its tools directly.</p></li><li><p><strong>Server tools:</strong> Deterministic host code composes MCP calls through <code>ctx.host.mcp</code>:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Search Linear issues.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  inputSchema: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">object</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ query: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() }),</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  async</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> execute</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">query</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ctx.host.mcp.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">callTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;linear&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;list_issues&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, { query });</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div></li><li><p><strong>Channel and schedule handlers:</strong> Webhooks hit MCP servers with no model turn at all, through <code>args.host.mcp</code>:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">POST</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;/sync&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  bodySchema: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">object</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({}),</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  handler</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">async</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">_req</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, { </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">host</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> result</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> host.mcp.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">callTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;linear&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;list_issues&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, {});</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Response.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">json</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(result);</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div></li></ol><p>The host registry is small: <code>host.mcp.names()</code> lists MCP connection names, and <code>listTools(name)</code> / <code>callTool(name, tool, args)</code> open the client lazily on first use.</p><h2 id="what-s-next" tabindex="-1">What&#39;s next <a class="header-anchor" href="#what-s-next" aria-label="Permalink to &quot;What&#39;s next&quot;">​</a></h2><p>Continue with these pages:</p><ul><li><a href="./../guides/agent-to-agent.html">Agent-to-agent</a>: peers in depth</li><li><a href="./tools.html">Tools</a>: authored tools that wrap MCP connections</li><li><a href="./../guides/webhooks.html">Webhooks</a>: calling MCP connections from handlers</li></ul>`,27)])])}const E=i(t,[["render",h]]);export{d as __pageData,E as default};

package/dist/docs/assets/reference_connections.md.C3vNH_DE.lean.js

@@ -0,0 +1 @@
+import{_ as i,c as e,o as a,ag as n}from"./chunks/framework.CAZyNGu9.js";const d=JSON.parse(`{"title":"MCP Connections","description":"Pull in tools from MCP servers: remote, stdio, the signed-in Cursor account's connectors, and peer agents.","frontmatter":{"title":"MCP Connections","description":"Pull in tools from MCP servers: remote, stdio, the signed-in Cursor account's connectors, and peer agents."},"headers":[],"relativePath":"reference/connections.md","filePath":"reference/connections.md"}`),t={name:"reference/connections.md"};function h(l,s,o,p,r,c){return a(),e("div",null,[...s[0]||(s[0]=[n("",27)])])}const E=i(t,[["render",h]]);export{d as __pageData,E as default};