wehub-resource-sync
bcbd1bdb22
Integ / changes (push) Has been skipped
Pre-commit / pre-commit (push) Failing after 1s
CLI exit codes / changes (push) Has been skipped
Test (Install) / changes (push) Has been skipped
Test (Python) / changes (push) Has been skipped
Test (TypeScript) / changes (push) Has been skipped
CLI exit codes / cli-gate (push) Has been cancelled
Test (Install) / test-install-gate (push) Has been cancelled
Integ / integ-gate (push) Has been cancelled
Test (Python) / test-python-gate (push) Has been cancelled
Test (TypeScript) / test-typescript-gate (push) Has been cancelled
Test (Install) / python-minimal (3.12) (push) Has been cancelled
Test (Install) / python-minimal (3.11) (push) Has been cancelled
Test (Install) / python-extra (agno, mirage.agents.agno) (push) Has been cancelled
Test (Install) / python-extra (chroma, mirage.resource.chroma) (push) Has been cancelled
Test (Install) / python-extra (pdf, mirage.core.filetype.pdf) (push) Has been cancelled
Integ / integ (push) Has been cancelled
Integ / integ-database (push) Has been cancelled
Integ / integ-database-ts (push) Has been cancelled
Integ / integ-data (push) Has been cancelled
Integ / integ-ssh (push) Has been cancelled
Integ / integ-ssh-ts (push) Has been cancelled
Test (Python) / audit (push) Has been cancelled
Test (TypeScript) / test (push) Has been cancelled
Test (TypeScript) / python-fs-shim (push) Has been cancelled
CLI exit codes / Python CLI (push) Has been cancelled
CLI exit codes / TypeScript CLI (push) Has been cancelled
CLI exit codes / Cross-language snapshot interop (push) Has been cancelled
Test (Python) / test (push) Has been cancelled
Test (Python) / import-isolation (deepagents, openai, mirage.agents.openai_agents) (push) Has been cancelled
Test (Python) / import-isolation (deepagents, pydantic-ai, mirage.agents.pydantic_ai) (push) Has been cancelled
Integ / integ-ts (push) Has been cancelled
Integ / integ-fuse (push) Has been cancelled
Test (Install) / python-extra (databricks, mirage.resource.databricks_volume) (push) Has been cancelled
Test (Install) / python-extra (deepagents, mirage.agents.langchain) (push) Has been cancelled
Test (Install) / python-extra (email, mirage.resource.email) (push) Has been cancelled
Test (Install) / python-extra (fuse, mirage.fuse.mount) (push) Has been cancelled
Test (Install) / python-extra (hdf5, mirage.core.filetype.hdf5) (push) Has been cancelled
Test (Install) / python-extra (hf, mirage.resource.hf_buckets) (push) Has been cancelled
Test (Install) / python-extra (lancedb, mirage.resource.lancedb) (push) Has been cancelled
Test (Install) / python-extra (langfuse, mirage.resource.langfuse) (push) Has been cancelled
Test (Install) / python-extra (mongodb, mirage.resource.mongodb) (push) Has been cancelled
Test (Install) / python-extra (nextcloud, mirage.resource.nextcloud) (push) Has been cancelled
Test (Install) / python-extra (openai, mirage.agents.openai_agents) (push) Has been cancelled
Test (Install) / python-extra (openhands, mirage.agents.openhands, 3.12) (push) Has been cancelled
Test (Install) / python-extra (parquet, mirage.core.filetype.parquet) (push) Has been cancelled
Test (Install) / python-extra (postgres, mirage.resource.postgres) (push) Has been cancelled
Test (Install) / python-extra (pydantic-ai, mirage.agents.pydantic_ai) (push) Has been cancelled
Test (Install) / python-extra (qdrant, mirage.resource.qdrant) (push) Has been cancelled
Test (Install) / python-extra (redis, mirage.resource.redis) (push) Has been cancelled
Test (Install) / python-extra (s3, mirage.resource.s3) (push) Has been cancelled
Test (Install) / python-extra (ssh, mirage.resource.ssh) (push) Has been cancelled
Test (Install) / ts-minimal (push) Has been cancelled
73 lines
2.7 KiB
Plaintext
73 lines
2.7 KiB
Plaintext
---
|
|
title: Claude Agent SDK
|
|
description: Run Anthropic's Claude Agent SDK against a Mirage workspace via an in-process MCP server exposing execute, read, write, edit, ls, and grep tools.
|
|
icon: /images/claude-logo.svg
|
|
---
|
|
|
|
The [Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/) builds agents on Claude. Mirage exposes any `Workspace` to the SDK as an in-process MCP server, so every file and shell operation the agent runs is routed through Mirage instead of the host filesystem.
|
|
|
|
This is distinct from [Claude Code](/python/agents/claude-code), which points the `claude` CLI at a [FUSE](/python/setup/fuse) mountpoint. Use this SDK integration when you build your own agent with `claude_agent_sdk.query()` and want Mirage tools rather than the built-in file tools.
|
|
|
|
## Install
|
|
|
|
```bash
|
|
uv add 'mirage-ai[claude-agent-sdk]'
|
|
```
|
|
|
|
## Usage
|
|
|
|
`build_options` wires a workspace into a ready-to-use `ClaudeAgentOptions`: it registers the Mirage MCP server, restricts the agent to Mirage's tools, and injects a system prompt describing the mounted paths.
|
|
|
|
```python
|
|
from claude_agent_sdk import query
|
|
|
|
from mirage import Workspace
|
|
from mirage.agents.claude_agent_sdk import build_options
|
|
from mirage.resource.s3 import S3Config, S3Resource
|
|
|
|
ws = Workspace({"/s3": S3Resource(S3Config(bucket="my-bucket"))})
|
|
|
|
async for msg in query(
|
|
prompt="cat /s3/data.csv | grep error",
|
|
options=build_options(ws),
|
|
):
|
|
print(msg)
|
|
```
|
|
|
|
## Composing with other MCP servers
|
|
|
|
Use `MirageServer` directly to combine Mirage with other servers:
|
|
|
|
```python
|
|
from claude_agent_sdk import ClaudeAgentOptions
|
|
|
|
from mirage.agents.claude_agent_sdk import MirageServer, build_system_prompt
|
|
|
|
options = ClaudeAgentOptions(
|
|
mcp_servers={"mirage": MirageServer(ws), "github": github_server},
|
|
allowed_tools=["mcp__mirage__*", "mcp__github__*"],
|
|
tools=[],
|
|
system_prompt=build_system_prompt(workspace=ws),
|
|
)
|
|
```
|
|
|
|
## Tools
|
|
|
|
| Tool | Maps to |
|
|
| --- | --- |
|
|
| `execute_command` | `Workspace.execute()`, the full shell pipeline (cat, grep, find, pipe, ...). |
|
|
| `read` | Line-paginated file read with `offset` and `limit`. |
|
|
| `write` | Create a new file (fails if it already exists). |
|
|
| `edit` | Replace a string in an existing file. |
|
|
| `ls` | List a directory. |
|
|
| `grep` | Recursive `grep -rn` over the workspace. |
|
|
|
|
## Exports
|
|
|
|
| Symbol | Purpose |
|
|
| --- | --- |
|
|
| `MirageServer` | In-process MCP server exposing the Mirage tools; pass to `ClaudeAgentOptions(mcp_servers=...)`. |
|
|
| `build_options` | Returns a ready-to-use `ClaudeAgentOptions` backed by a workspace. |
|
|
| `build_system_prompt` | Generates a system prompt that describes mounted paths to the model. |
|
|
| `MIRAGE_SYSTEM_PROMPT` | The default system prompt template. |
|