@codeany/open-agent-sdk 0.1.0

package/.env.example

@@ -0,0 +1,8 @@
+# Required: your LLM API key
+CODEANY_API_KEY=sk-or-...
+
+# Optional: override model
+# CODEANY_MODEL=anthropic/claude-sonnet-4
+
+# Optional: custom API endpoint (e.g. third-party proxy)
+# CODEANY_BASE_URL=https://openrouter.ai/api

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 CodeAny (https://codeany.ai)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,388 @@
+# Open Agent SDK (TypeScript)
+
+[![npm version](https://img.shields.io/npm/v/@codeany/open-agent-sdk)](https://www.npmjs.com/package/@codeany/open-agent-sdk)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+
+Open-source Agent SDK that runs the full agent loop **in-process** — no subprocess or CLI required. Deploy anywhere: cloud, serverless, Docker, CI/CD.
+
+Also available in **Go**: [open-agent-sdk-go](https://github.com/codeany-ai/open-agent-sdk-go)
+
+## Get started
+
+```bash
+npm install @codeany/open-agent-sdk
+```
+
+Set your API key:
+
+```bash
+export CODEANY_API_KEY=your-api-key
+```
+
+Third-party providers (e.g. OpenRouter) are supported via `CODEANY_BASE_URL`:
+
+```bash
+export CODEANY_BASE_URL=https://openrouter.ai/api
+export CODEANY_API_KEY=sk-or-...
+export CODEANY_MODEL=anthropic/claude-sonnet-4
+```
+
+## Quick start
+
+### One-shot query (streaming)
+
+```typescript
+import { query } from "@codeany/open-agent-sdk";
+
+for await (const message of query({
+  prompt: "Read package.json and tell me the project name.",
+  options: {
+    allowedTools: ["Read", "Glob"],
+    permissionMode: "bypassPermissions",
+  },
+})) {
+  if (message.type === "assistant") {
+    for (const block of message.message.content) {
+      if ("text" in block) console.log(block.text);
+    }
+  }
+}
+```
+
+### Simple blocking prompt
+
+```typescript
+import { createAgent } from "@codeany/open-agent-sdk";
+
+const agent = createAgent({ model: "claude-sonnet-4-6" });
+const result = await agent.prompt("What files are in this project?");
+
+console.log(result.text);
+console.log(
+  `Turns: ${result.num_turns}, Tokens: ${result.usage.input_tokens + result.usage.output_tokens}`,
+);
+```
+
+### Multi-turn conversation
+
+```typescript
+import { createAgent } from "@codeany/open-agent-sdk";
+
+const agent = createAgent({ maxTurns: 5 });
+
+const r1 = await agent.prompt(
+  'Create a file /tmp/hello.txt with "Hello World"',
+);
+console.log(r1.text);
+
+const r2 = await agent.prompt("Read back the file you just created");
+console.log(r2.text);
+
+console.log(`Session messages: ${agent.getMessages().length}`);
+```
+
+### Custom tools (Zod schema)
+
+```typescript
+import { z } from "zod";
+import { query, tool, createSdkMcpServer } from "@codeany/open-agent-sdk";
+
+const getWeather = tool(
+  "get_weather",
+  "Get the temperature for a city",
+  { city: z.string().describe("City name") },
+  async ({ city }) => ({
+    content: [{ type: "text", text: `${city}: 22°C, sunny` }],
+  }),
+);
+
+const server = createSdkMcpServer({ name: "weather", tools: [getWeather] });
+
+for await (const msg of query({
+  prompt: "What is the weather in Tokyo?",
+  options: { mcpServers: { weather: server } },
+})) {
+  if (msg.type === "result")
+    console.log(`Done: $${msg.total_cost_usd?.toFixed(4)}`);
+}
+```
+
+### Custom tools (low-level)
+
+```typescript
+import {
+  createAgent,
+  getAllBaseTools,
+  defineTool,
+} from "@codeany/open-agent-sdk";
+
+const calculator = defineTool({
+  name: "Calculator",
+  description: "Evaluate a math expression",
+  inputSchema: {
+    type: "object",
+    properties: { expression: { type: "string" } },
+    required: ["expression"],
+  },
+  isReadOnly: true,
+  async call(input) {
+    const result = Function(`'use strict'; return (${input.expression})`)();
+    return `${input.expression} = ${result}`;
+  },
+});
+
+const agent = createAgent({ tools: [...getAllBaseTools(), calculator] });
+const r = await agent.prompt("Calculate 2**10 * 3");
+console.log(r.text);
+```
+
+### MCP server integration
+
+```typescript
+import { createAgent } from "@codeany/open-agent-sdk";
+
+const agent = createAgent({
+  mcpServers: {
+    filesystem: {
+      command: "npx",
+      args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
+    },
+  },
+});
+
+const result = await agent.prompt("List files in /tmp");
+console.log(result.text);
+await agent.close();
+```
+
+### Subagents
+
+```typescript
+import { query } from "@codeany/open-agent-sdk";
+
+for await (const msg of query({
+  prompt: "Use the code-reviewer agent to review src/index.ts",
+  options: {
+    agents: {
+      "code-reviewer": {
+        description: "Expert code reviewer",
+        prompt: "Analyze code quality. Focus on security and performance.",
+        tools: ["Read", "Glob", "Grep"],
+      },
+    },
+  },
+})) {
+  if (msg.type === "result") console.log("Done");
+}
+```
+
+### Permissions
+
+```typescript
+import { query } from "@codeany/open-agent-sdk";
+
+// Read-only agent — can only analyze, not modify
+for await (const msg of query({
+  prompt: "Review the code in src/ for best practices.",
+  options: {
+    allowedTools: ["Read", "Glob", "Grep"],
+    permissionMode: "dontAsk",
+  },
+})) {
+  // ...
+}
+```
+
+### Web UI
+
+A built-in web chat interface is included for testing:
+
+```bash
+npx tsx examples/web/server.ts
+# Open http://localhost:8081
+```
+
+## API reference
+
+### Top-level functions
+
+| Function                              | Description                                                    |
+| ------------------------------------- | -------------------------------------------------------------- |
+| `query({ prompt, options })`          | One-shot streaming query, returns `AsyncGenerator<SDKMessage>` |
+| `createAgent(options)`                | Create a reusable agent with session persistence               |
+| `tool(name, desc, schema, handler)`   | Create a tool with Zod schema validation                       |
+| `createSdkMcpServer({ name, tools })` | Bundle tools into an in-process MCP server                     |
+| `defineTool(config)`                  | Low-level tool definition helper                               |
+| `getAllBaseTools()`                   | Get all 34 built-in tools                                      |
+| `listSessions()`                      | List persisted sessions                                        |
+| `getSessionMessages(id)`              | Retrieve messages from a session                               |
+| `forkSession(id)`                     | Fork a session for branching                                   |
+
+### Agent methods
+
+| Method                          | Description                                           |
+| ------------------------------- | ----------------------------------------------------- |
+| `agent.query(prompt)`           | Streaming query, returns `AsyncGenerator<SDKMessage>` |
+| `agent.prompt(text)`            | Blocking query, returns `Promise<QueryResult>`        |
+| `agent.getMessages()`           | Get conversation history                              |
+| `agent.clear()`                 | Reset session                                         |
+| `agent.interrupt()`             | Abort current query                                   |
+| `agent.setModel(model)`         | Change model mid-session                              |
+| `agent.setPermissionMode(mode)` | Change permission mode                                |
+| `agent.close()`                 | Close MCP connections, persist session                |
+
+### Options
+
+| Option               | Type                                    | Default                | Description                                                          |
+| -------------------- | --------------------------------------- | ---------------------- | -------------------------------------------------------------------- |
+| `model`              | `string`                                | `claude-sonnet-4-6`    | LLM model ID                                                         |
+| `apiKey`             | `string`                                | `CODEANY_API_KEY`      | API key                                                              |
+| `baseURL`            | `string`                                | —                      | Custom API endpoint                                                  |
+| `cwd`                | `string`                                | `process.cwd()`        | Working directory                                                    |
+| `systemPrompt`       | `string`                                | —                      | System prompt override                                               |
+| `appendSystemPrompt` | `string`                                | —                      | Append to default system prompt                                      |
+| `tools`              | `ToolDefinition[]`                      | All built-in           | Available tools                                                      |
+| `allowedTools`       | `string[]`                              | —                      | Tool allow-list                                                      |
+| `disallowedTools`    | `string[]`                              | —                      | Tool deny-list                                                       |
+| `permissionMode`     | `string`                                | `bypassPermissions`    | `default` / `acceptEdits` / `dontAsk` / `bypassPermissions` / `plan` |
+| `canUseTool`         | `function`                              | —                      | Custom permission callback                                           |
+| `maxTurns`           | `number`                                | `10`                   | Max agentic turns                                                    |
+| `maxBudgetUsd`       | `number`                                | —                      | Spending cap                                                         |
+| `thinking`           | `ThinkingConfig`                        | `{ type: 'adaptive' }` | Extended thinking                                                    |
+| `effort`             | `string`                                | `high`                 | Reasoning effort: `low` / `medium` / `high` / `max`                  |
+| `mcpServers`         | `Record<string, McpServerConfig>`       | —                      | MCP server connections                                               |
+| `agents`             | `Record<string, AgentDefinition>`       | —                      | Subagent definitions                                                 |
+| `hooks`              | `Record<string, HookCallbackMatcher[]>` | —                      | Lifecycle hooks                                                      |
+| `resume`             | `string`                                | —                      | Resume session by ID                                                 |
+| `continue`           | `boolean`                               | `false`                | Continue most recent session                                         |
+| `persistSession`     | `boolean`                               | `true`                 | Persist session to disk                                              |
+| `sessionId`          | `string`                                | auto                   | Explicit session ID                                                  |
+| `outputFormat`       | `{ type: 'json_schema', schema }`       | —                      | Structured output                                                    |
+| `sandbox`            | `SandboxSettings`                       | —                      | Filesystem/network sandbox                                           |
+| `settingSources`     | `SettingSource[]`                       | —                      | Load AGENT.md, project settings                                      |
+| `env`                | `Record<string, string>`                | —                      | Environment variables                                                |
+| `abortController`    | `AbortController`                       | —                      | Cancellation controller                                              |
+
+### Environment variables
+
+| Variable             | Description            |
+| -------------------- | ---------------------- |
+| `CODEANY_API_KEY`    | API key (required)     |
+| `CODEANY_MODEL`      | Default model override |
+| `CODEANY_BASE_URL`   | Custom API endpoint    |
+| `CODEANY_AUTH_TOKEN` | Alternative auth token |
+
+## Built-in tools
+
+| Tool                                       | Description                                  |
+| ------------------------------------------ | -------------------------------------------- |
+| **Bash**                                   | Execute shell commands                       |
+| **Read**                                   | Read files with line numbers                 |
+| **Write**                                  | Create / overwrite files                     |
+| **Edit**                                   | Precise string replacement in files          |
+| **Glob**                                   | Find files by pattern                        |
+| **Grep**                                   | Search file contents with regex              |
+| **WebFetch**                               | Fetch and parse web content                  |
+| **WebSearch**                              | Search the web                               |
+| **NotebookEdit**                           | Edit Jupyter notebook cells                  |
+| **Agent**                                  | Spawn subagents for parallel work            |
+| **TaskCreate/List/Update/Get/Stop/Output** | Task management system                       |
+| **TeamCreate/Delete**                      | Multi-agent team coordination                |
+| **SendMessage**                            | Inter-agent messaging                        |
+| **EnterWorktree/ExitWorktree**             | Git worktree isolation                       |
+| **EnterPlanMode/ExitPlanMode**             | Structured planning workflow                 |
+| **AskUserQuestion**                        | Ask the user for input                       |
+| **ToolSearch**                             | Discover lazy-loaded tools                   |
+| **ListMcpResources/ReadMcpResource**       | MCP resource access                          |
+| **CronCreate/Delete/List**                 | Scheduled task management                    |
+| **RemoteTrigger**                          | Remote agent triggers                        |
+| **LSP**                                    | Language Server Protocol (code intelligence) |
+| **Config**                                 | Dynamic configuration                        |
+| **TodoWrite**                              | Session todo list                            |
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────┐
+│                   Your Application                    │
+│                                                       │
+│   import { createAgent } from '@codeany/open-agent-sdk' │
+└────────────────────────┬─────────────────────────────┘
+                         │
+              ┌──────────▼──────────┐
+              │       Agent         │  Session state, tool pool,
+              │  query() / prompt() │  MCP connections
+              └──────────┬──────────┘
+                         │
+              ┌──────────▼──────────┐
+              │    QueryEngine      │  Agentic loop:
+              │   submitMessage()   │  API call → tools → repeat
+              └──────────┬──────────┘
+                         │
+         ┌───────────────┼───────────────┐
+         │               │               │
+   ┌─────▼─────┐  ┌─────▼─────┐  ┌─────▼─────┐
+   │  LLM API  │  │  34 Tools │  │    MCP     │
+   │  Client   │  │ Bash,Read │  │  Servers   │
+   │ (streaming)│  │ Edit,...  │  │ stdio/SSE/ │
+   └───────────┘  └───────────┘  │ HTTP/SDK   │
+                                  └───────────┘
+```
+
+**Key internals:**
+
+| Component             | Description                                                      |
+| --------------------- | ---------------------------------------------------------------- |
+| **QueryEngine**       | Core agentic loop with auto-compact, retry, tool orchestration   |
+| **Auto-compact**      | Summarizes conversation when context window fills up             |
+| **Micro-compact**     | Truncates oversized tool results                                 |
+| **Retry**             | Exponential backoff for rate limits and transient errors         |
+| **Token estimation**  | Rough token counting for budget and compaction thresholds        |
+| **File cache**        | LRU cache (100 entries, 25 MB) for file reads                    |
+| **Hook system**       | 20 lifecycle events (PreToolUse, PostToolUse, SessionStart, ...) |
+| **Session storage**   | Persist / resume / fork sessions on disk                         |
+| **Context injection** | Git status + AGENT.md automatically injected into system prompt  |
+
+## Examples
+
+| #   | File                                  | Description                            |
+| --- | ------------------------------------- | -------------------------------------- |
+| 01  | `examples/01-simple-query.ts`         | Streaming query with event handling    |
+| 02  | `examples/02-multi-tool.ts`           | Multi-tool orchestration (Glob + Bash) |
+| 03  | `examples/03-multi-turn.ts`           | Multi-turn session persistence         |
+| 04  | `examples/04-prompt-api.ts`           | Blocking `prompt()` API                |
+| 05  | `examples/05-custom-system-prompt.ts` | Custom system prompt                   |
+| 06  | `examples/06-mcp-server.ts`           | MCP server integration                 |
+| 07  | `examples/07-custom-tools.ts`         | Custom tools with `defineTool()`       |
+| 08  | `examples/08-official-api-compat.ts`  | `query()` API pattern                  |
+| 09  | `examples/09-subagents.ts`            | Subagent delegation                    |
+| 10  | `examples/10-permissions.ts`          | Read-only agent with tool restrictions |
+| 11  | `examples/11-custom-mcp-tools.ts`     | `tool()` + `createSdkMcpServer()`      |
+| web | `examples/web/`                       | Web chat UI for testing                |
+
+Run any example:
+
+```bash
+npx tsx examples/01-simple-query.ts
+```
+
+Start the web UI:
+
+```bash
+npx tsx examples/web/server.ts
+```
+
+## Star History
+
+<a href="https://www.star-history.com/?repos=shipany-ai%2Fopen-agent-sdk&type=timeline&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/image?repos=shipany-ai/open-agent-sdk&type=timeline&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/image?repos=shipany-ai/open-agent-sdk&type=timeline&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/image?repos=shipany-ai/open-agent-sdk&type=timeline&legend=top-left" />
+ </picture>
+</a>
+
+## License
+
+MIT

package/examples/01-simple-query.ts

@@ -0,0 +1,43 @@
+/**
+ * Example 1: Simple Query with Streaming
+ *
+ * Demonstrates the basic createAgent() + query() flow with
+ * real-time event streaming.
+ *
+ * Run: npx tsx examples/01-simple-query.ts
+ */
+import { createAgent } from '../src/index.js'
+
+async function main() {
+  console.log('--- Example 1: Simple Query ---\n')
+
+  const agent = createAgent({
+    model: process.env.CODEANY_MODEL || 'claude-sonnet-4-6',
+    maxTurns: 10,
+  })
+
+  for await (const event of agent.query(
+    'Read package.json and tell me the project name and version in one sentence.',
+  )) {
+    const msg = event as any
+
+    if (msg.type === 'assistant') {
+      // Print tool calls
+      for (const block of msg.message?.content || []) {
+        if (block.type === 'tool_use') {
+          console.log(`[Tool] ${block.name}(${JSON.stringify(block.input).slice(0, 80)})`)
+        }
+        if (block.type === 'text') {
+          console.log(`\nAssistant: ${block.text}`)
+        }
+      }
+    }
+
+    if (msg.type === 'result') {
+      console.log(`\n--- Result: ${msg.subtype} ---`)
+      console.log(`Tokens: ${msg.usage?.input_tokens} in / ${msg.usage?.output_tokens} out`)
+    }
+  }
+}
+
+main().catch(console.error)

package/examples/02-multi-tool.ts

@@ -0,0 +1,44 @@
+/**
+ * Example 2: Multi-Tool Orchestration
+ *
+ * The agent autonomously uses Glob, Bash, and Read tools to
+ * accomplish a multi-step task.
+ *
+ * Run: npx tsx examples/02-multi-tool.ts
+ */
+import { createAgent } from '../src/index.js'
+
+async function main() {
+  console.log('--- Example 2: Multi-Tool Orchestration ---\n')
+
+  const agent = createAgent({
+    model: process.env.CODEANY_MODEL || 'claude-sonnet-4-6',
+    maxTurns: 15,
+  })
+
+  for await (const event of agent.query(
+    'Do these steps: ' +
+    '1) Use Glob to find all .ts files in src/ (pattern "src/*.ts"). ' +
+    '2) Use Bash to count lines in src/agent.ts with `wc -l`. ' +
+    '3) Give a brief summary.',
+  )) {
+    const msg = event as any
+
+    if (msg.type === 'assistant') {
+      for (const block of msg.message?.content || []) {
+        if (block.type === 'tool_use') {
+          console.log(`[${block.name}] ${JSON.stringify(block.input).slice(0, 100)}`)
+        }
+        if (block.type === 'text' && block.text.trim()) {
+          console.log(`\n${block.text}`)
+        }
+      }
+    }
+
+    if (msg.type === 'result') {
+      console.log(`\n--- ${msg.subtype} | ${msg.usage?.input_tokens}/${msg.usage?.output_tokens} tokens ---`)
+    }
+  }
+}
+
+main().catch(console.error)

package/examples/03-multi-turn.ts

@@ -0,0 +1,39 @@
+/**
+ * Example 3: Multi-Turn Conversation
+ *
+ * Demonstrates session persistence across multiple turns.
+ * The agent remembers context from previous interactions.
+ *
+ * Run: npx tsx examples/03-multi-turn.ts
+ */
+import { createAgent } from '../src/index.js'
+
+async function main() {
+  console.log('--- Example 3: Multi-Turn Conversation ---\n')
+
+  const agent = createAgent({
+    model: process.env.CODEANY_MODEL || 'claude-sonnet-4-6',
+    maxTurns: 5,
+  })
+
+  // Turn 1: Create a file
+  console.log('> Turn 1: Create a file')
+  const r1 = await agent.prompt(
+    'Use Bash to run: echo "Hello Open Agent SDK" > /tmp/oas-test.txt. Confirm briefly.',
+  )
+  console.log(`  ${r1.text}\n`)
+
+  // Turn 2: Read back (should remember context)
+  console.log('> Turn 2: Read the file back')
+  const r2 = await agent.prompt('Read the file you just created and tell me its contents.')
+  console.log(`  ${r2.text}\n`)
+
+  // Turn 3: Clean up
+  console.log('> Turn 3: Cleanup')
+  const r3 = await agent.prompt('Delete that file with Bash. Confirm.')
+  console.log(`  ${r3.text}\n`)
+
+  console.log(`Session history: ${agent.getMessages().length} messages`)
+}
+
+main().catch(console.error)

package/examples/04-prompt-api.ts

@@ -0,0 +1,29 @@
+/**
+ * Example 4: Simple Prompt API
+ *
+ * Uses the blocking prompt() method for quick one-shot queries.
+ * No need to iterate over streaming events.
+ *
+ * Run: npx tsx examples/04-prompt-api.ts
+ */
+import { createAgent } from '../src/index.js'
+
+async function main() {
+  console.log('--- Example 4: Simple Prompt API ---\n')
+
+  const agent = createAgent({
+    model: process.env.CODEANY_MODEL || 'claude-sonnet-4-6',
+    maxTurns: 5,
+  })
+
+  const result = await agent.prompt(
+    'Use Bash to run `node --version` and `npm --version`, then tell me the versions.',
+  )
+
+  console.log(`Answer: ${result.text}`)
+  console.log(`Turns: ${result.num_turns}`)
+  console.log(`Tokens: ${result.usage.input_tokens} in / ${result.usage.output_tokens} out`)
+  console.log(`Duration: ${result.duration_ms}ms`)
+}
+
+main().catch(console.error)

package/examples/05-custom-system-prompt.ts

@@ -0,0 +1,26 @@
+/**
+ * Example 5: Custom System Prompt
+ *
+ * Shows how to customize the agent's behavior with a system prompt.
+ *
+ * Run: npx tsx examples/05-custom-system-prompt.ts
+ */
+import { createAgent } from '../src/index.js'
+
+async function main() {
+  console.log('--- Example 5: Custom System Prompt ---\n')
+
+  const agent = createAgent({
+    model: process.env.CODEANY_MODEL || 'claude-sonnet-4-6',
+    maxTurns: 5,
+    systemPrompt:
+      'You are a senior code reviewer. When asked to review code, focus on: ' +
+      '1) Security issues, 2) Performance concerns, 3) Maintainability. ' +
+      'Be concise and use bullet points.',
+  })
+
+  const result = await agent.prompt('Read src/agent.ts and give a brief code review.')
+  console.log(result.text)
+}
+
+main().catch(console.error)

package/examples/06-mcp-server.ts

@@ -0,0 +1,49 @@
+/**
+ * Example 6: MCP Server Integration
+ *
+ * Connects to an MCP (Model Context Protocol) server and uses
+ * its tools through the agent. This example uses the filesystem
+ * MCP server as a demonstration.
+ *
+ * Prerequisites:
+ *   npm install -g @modelcontextprotocol/server-filesystem
+ *
+ * Run: npx tsx examples/06-mcp-server.ts
+ */
+import { createAgent } from '../src/index.js'
+
+async function main() {
+  console.log('--- Example 6: MCP Server Integration ---\n')
+
+  const agent = createAgent({
+    model: process.env.CODEANY_MODEL || 'claude-sonnet-4-6',
+    maxTurns: 10,
+    mcpServers: {
+      filesystem: {
+        command: 'npx',
+        args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
+      },
+    },
+  })
+
+  console.log('Connecting to MCP filesystem server...\n')
+
+  const result = await agent.prompt(
+    'Use the filesystem MCP tools to list files in /tmp. Be brief.',
+  )
+
+  console.log(`Answer: ${result.text}`)
+  console.log(`Turns: ${result.num_turns}`)
+
+  await agent.close()
+}
+
+main().catch(e => {
+  console.error('Error:', e.message)
+  if (e.message.includes('ENOENT') || e.message.includes('not found')) {
+    console.error(
+      '\nMCP server not found. Install it with:\n' +
+      '  npm install -g @modelcontextprotocol/server-filesystem\n',
+    )
+  }
+})