akillness claude-agent-sdk
Claude Agent SDK is a leading agent sdk in the 2026 AI agent engineering landscape (7.5k★).
When to use this skill
- Build agents on the Claude Code harness programmatically (query() one-shot / ClaudeSDKClient interactive)
- ClaudeAgentOptions: allowed_tools, permission_mode, cwd, mcp_servers, system_prompt
- In-process custom tools via @tool + create_sdk_mcp_server (no subprocess MCP needed)
- Hooks (PreToolUse/PostToolUse...) for deterministic control of the agent loop
- Subagents (agents option) and session resume/fork
- Bundled Claude Code CLI in the wheel; also drives an existing CLI install
- Ecosystem overlap: Complements agent-configuration (covers CLAUDE.md/hooks at product level) — SDK-level engineering is uncovered; jeo-skills has openai-agents-python for the OpenAI equivalent
Installation
pip install claude-agent-sdk
Core API
import anyio
from claude_agent_sdk import query
async def main():
async for message in query(prompt="What is 2 + 2?"):
print(message)
anyio.run(main)
Instructions
Step 1: Initialize the environment
Verify you have Python installed and set up properly. Use the correct package manager (pip, npm, pnpm, uv) as specified in the installation section.
Step 2: Establish the agent flow
Architecture pattern: SDK wraps the Claude Code agent loop; tools are MCP servers (external or in-process SDK servers); hooks intercept lifecycle events; permission modes gate tool execution
Step 3: Implement tool integrations and policies
Integrate necessary tools, environment keys, and safety gates according to your architectural needs. Position in the ecosystem: Official Anthropic path to embed the Claude Code harness in apps; alternatives: deepagents (LangGraph), openai-agents SDK (different model vendor), pi-agent-core (vendor-neutral minimal)
Examples
Example 1: Minimal Agent Run
import anyio
from claude_agent_sdk import query
async def main():
async for message in query(prompt="What is 2 + 2?"):
print(message)
anyio.run(main)
Best practices
- Follow the primary installation commands for Claude Agent SDK to ensure dependencies are resolved correctly.
- Configure model providers and API keys securely before starting the runtime.
- Use appropriate sandboxing or permission isolation if executing AI-generated code.