diff --git a/99 Daily/2026-04-17.md b/99 Daily/2026-04-17.md index b64e490..56c5f51 100644 --- a/99 Daily/2026-04-17.md +++ b/99 Daily/2026-04-17.md @@ -242,3 +242,9 @@ tags: [daily] - 13:04 (<1min) | `memory-compiler` - **Asked:** Asked for WezTerm plugins article to be compiled into the knowledge base wiki structure. - **Done:** Created structured wiki article on WezTerm plugin installation, updates, removal, and local development workflows. +- 13:06 (<1min) | `memory-compiler` + - **Asked:** Compile a raw wiki article about Claude Code channels into the knowledge base structure. + - **Done:** Created `wiki/claude-code/channels.md` with channel features, platforms, security model, and enterprise controls; updated both index files. +- 13:06 (<1min) | `memory-compiler` + - **Asked:** Compile a new raw article into the knowledge base as a structured wiki article. + - **Done:** Created quickstart.md article documenting query() entry point, message streams, permissions, and customization with 6 wikilinks. diff --git a/raw/Push events into a running session with channels.md b/raw/_processed/Push events into a running session with channels.md similarity index 100% rename from raw/Push events into a running session with channels.md rename to raw/_processed/Push events into a running session with channels.md diff --git a/raw/Quickstart.md b/raw/_processed/Quickstart.md similarity index 100% rename from raw/Quickstart.md rename to raw/_processed/Quickstart.md diff --git a/wiki/_master-index.md b/wiki/_master-index.md index 093e7ed..507e63a 100644 --- a/wiki/_master-index.md +++ b/wiki/_master-index.md @@ -30,9 +30,9 @@ This 3-hop pattern works for hundreds of articles without vector search. | [[wiki/web-agency/_index\|web-agency/]] | AI-assisted website building & selling: Claude Code, Nanobanana 2, Kling, LaunchPath MCP | 1 | | [[wiki/dotfiles/_index\|dotfiles/]] | Linux terminal ricing: Kitty, Fish, WezTerm CLI, modern Rust CLI tools, LazyVim, unified themes, Tabby | 18 | -| [[wiki/agent-sdk/_index\|agent-sdk/]] | Claude Agent SDK (formerly Claude Code SDK) — build autonomous AI agents in Python and TypeScript | 17 | +| [[wiki/agent-sdk/_index\|agent-sdk/]] | Claude Agent SDK (formerly Claude Code SDK) — build autonomous AI agents in Python and TypeScript | 18 | | [[wiki/llm-models/_index\|llm-models/]] | OpenAI model catalog — GPT-5.x, o-series reasoning, audio/realtime, embeddings, moderation | 1 | -| [[wiki/claude-code/_index\|claude-code/]] | Claude Code product docs — install, capabilities, surfaces, MCP, hooks, scheduling, multi-agent, plugins, skills, error recovery | 8 | +| [[wiki/claude-code/_index\|claude-code/]] | Claude Code product docs — install, capabilities, surfaces, MCP, hooks, scheduling, multi-agent, plugins, skills, channels, error recovery | 9 | diff --git a/wiki/agent-sdk/_index.md b/wiki/agent-sdk/_index.md index 408a982..dd7de15 100644 --- a/wiki/agent-sdk/_index.md +++ b/wiki/agent-sdk/_index.md @@ -31,3 +31,4 @@ Build production AI agents using the same tools, agent loop, and context managem | [[wiki/agent-sdk/migration-guide\|migration-guide]] | Migrate from claude-code-sdk to claude-agent-sdk: package rename, import updates, v0.1.0 breaking changes (system prompt, settingSources) | raw/Migrate to Claude Agent SDK.md | 2026-04-17 | | [[wiki/agent-sdk/modifying-system-prompts\|modifying-system-prompts]] | Four methods to customize system prompts: CLAUDE.md, output styles, append preset, custom string; prompt caching with excludeDynamicSections | raw/Modifying system prompts.md, raw/Modifying system prompts 1.md | 2026-04-17 | | [[wiki/agent-sdk/observability-opentelemetry\|observability-opentelemetry]] | Export traces, metrics, log events via OTEL to any OTLP backend; span names, sensitive data controls, flush config | raw/Observability with OpenTelemetry.md | 2026-04-17 | +| [[wiki/agent-sdk/quickstart\|quickstart]] | Minimal working agent: query(), allowed_tools, permission modes, message stream types, troubleshooting | raw/Quickstart.md | 2026-04-17 | diff --git a/wiki/agent-sdk/quickstart.md b/wiki/agent-sdk/quickstart.md new file mode 100644 index 0000000..c5fa5a9 --- /dev/null +++ b/wiki/agent-sdk/quickstart.md @@ -0,0 +1,128 @@ +--- +title: "Agent SDK Quickstart" +aliases: [agent-sdk-quickstart, sdk-quickstart, getting-started-agent-sdk] +tags: [agent-sdk, quickstart, python, typescript, anthropic, claude] +sources: [raw/Quickstart.md] +created: 2026-04-17 +updated: 2026-04-17 +--- + +# Agent SDK Quickstart + +Build an AI agent that autonomously reads, analyzes, and fixes code — no manual intervention. + +## Prerequisites + +- **Python 3.10+** or **Node.js 18+** +- Anthropic account with `ANTHROPIC_API_KEY` set + +## Minimal Agent (Python) + +```python +import asyncio +from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage + +async def main(): + async for message in query( + prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.", + options=ClaudeAgentOptions( + allowed_tools=["Read", "Edit", "Glob"], + permission_mode="acceptEdits", + ), + ): + if isinstance(message, AssistantMessage): + for block in message.content: + if hasattr(block, "text"): + print(block.text) + elif hasattr(block, "name"): + print(f"Tool: {block.name}") + elif isinstance(message, ResultMessage): + print(f"Done: {message.subtype}") + +asyncio.run(main()) +``` + +## Three Core Parts + +| Part | What it does | +|------|-------------| +| `query()` | Main entry point — creates the agentic loop, returns an async iterator | +| `prompt` | Natural language task — Claude decides which tools to call | +| `options` | Config: `allowed_tools`, `permission_mode`, `system_prompt`, `mcpServers` | + +## Tools Reference + +| Tools | Agent capability | +|-------|----------------| +| `Read`, `Glob`, `Grep` | Read-only analysis | +| `Read`, `Edit`, `Glob` | Analyze and modify code | +| `Read`, `Edit`, `Bash`, `Glob`, `Grep` | Full automation | +| + `WebSearch` | Add web search capability | + +## Permission Modes + +| Mode | Behavior | Use case | +|------|----------|----------| +| `acceptEdits` | Auto-approves file edits + common FS commands | Trusted dev workflows | +| `dontAsk` | Denies anything not in `allowedTools` | Locked-down headless agents | +| `auto` *(TS only)* | Model classifier approves/denies each tool call | Autonomous with guardrails | +| `bypassPermissions` | No prompts at all | Sandboxed CI | +| `default` | Requires `canUseTool` callback | Custom approval flows | + +## Customization Examples + +**Custom system prompt:** +```python +options = ClaudeAgentOptions( + allowed_tools=["Read", "Edit", "Glob"], + permission_mode="acceptEdits", + system_prompt="You are a senior Python developer. Always follow PEP 8.", +) +``` + +**Add Bash for full automation:** +```python +options = ClaudeAgentOptions( + allowed_tools=["Read", "Edit", "Glob", "Bash"], + permission_mode="acceptEdits", +) +# Prompt: "Write unit tests for utils.py, run them, and fix any failures" +``` + +## Message Stream Types + +The `async for` loop yields four message types: +1. **AssistantMessage** — Claude's reasoning text + tool calls +2. **Tool result** — output from each tool execution +3. **ResultMessage** — final outcome (`subtype` = success/error/etc.) +4. System/internal state (filter out for clean output) + +See [[wiki/agent-sdk/agent-loop|agent-loop]] for the full message lifecycle. + +## Troubleshooting + +| Error | Fix | +|-------|-----| +| `API key not found` | Set `ANTHROPIC_API_KEY` env var | +| `thinking.type.enabled not supported` | Upgrade to Agent SDK v0.2.111+ (Opus 4.7 changed to `thinking.type.adaptive`) | + +## Key Takeaways + +- `query()` is the single entry point — it drives the full agentic loop with `async for` +- `allowed_tools` pre-approves tools; `permission_mode="acceptEdits"` removes interactive prompts +- The loop ends when Claude finishes the task or hits an error — SDK handles orchestration +- Streaming (async for) is for real-time output; collect all messages for background/CI jobs +- `system_prompt` and `mcpServers` in `ClaudeAgentOptions` are the main extension points + +## Next Steps + +- [[wiki/agent-sdk/configure-permissions|configure-permissions]] — full permission modes + allow/deny rules +- [[wiki/agent-sdk/sdk-hooks|sdk-hooks]] — intercept tool calls with PreToolUse/PostToolUse +- [[wiki/agent-sdk/mcp-integration|mcp-integration]] — connect to databases, browsers, external APIs +- [[wiki/agent-sdk/hosting-production|hosting-production]] — deploy to Docker, cloud, CI/CD +- [[wiki/agent-sdk/user-input-approvals|user-input-approvals]] — `canUseTool` callback for custom approval flows +- [[wiki/agent-sdk/agent-loop|agent-loop]] — understand message lifecycle and context management + +--- + +*Source: raw/Quickstart.md*