Claude Code Agent SDK — Custom AI Agent Development Guide | Python Implementation and Multi-Agent Architecture

What Is Agent SDK — Extending Claude Code with Python

The Claude Code Agent SDK is the official SDK that enables Python scripts to utilize all Claude Code tools (Read, Write, Edit, Bash, Grep, etc.) and capabilities. Unlike standard Claude API, it comes with built-in 'agent capabilities' including filesystem access, command execution, and multi-step reasoning. This enables advanced implementations beyond Claude Code's standard interface: AI agents with custom tools, multi-agent systems coordinating multiple sub-agents, and automated agents embedded in CI/CD pipelines. Enterprise companies in Shinagawa and Minato wards have implemented automated pull request reviews, API documentation generation, and test case creation using Agent SDK, achieving significant acceleration in development cycles.

Installation and Setup — pip install claude-agent-sdk

Setting up Agent SDK is straightforward: ```bash pip install claude-agent-sdk ``` Set your API key in the `ANTHROPIC_API_KEY` environment variable or specify it explicitly in code: ```python import os os.environ["ANTHROPIC_API_KEY"] = "sk-ant-..." ``` **Basic project structure**: ``` project/ ├── agents/ │ ├── reviewer.py # Code review agent │ ├── doc_gen.py # Documentation generation agent │ └── utils.py # Common utilities ├── .env # API key (recommended in .gitignore) └── requirements.txt ``` A Shibuya-based startup manages multiple specialized agents with this structure, reusing them across the team.

query() and ClaudeSDKClient — Basic Agent Execution

The simplest agent execution uses the `query()` function: ```python from claude_agent_sdk import query result = query( "Analyze the codebase and identify potential security vulnerabilities", cwd="/path/to/project" ) print(result["output"]) ``` This alone executes an agent using all Claude Code capabilities (file search, code analysis, multi-file reading). **For custom tools and Hooks**, use `ClaudeSDKClient`: ```python from claude_agent_sdk import ClaudeSDKClient, Tool client = ClaudeSDKClient() result = client.query( prompt="Review this PR", tools=[custom_tool], hooks=[pre_commit_hook], cwd="/path/to/project" ) ``` A web production company in Minato ward built a fully automated delivery pipeline using ClaudeSDKClient with project-specific build and deployment tools.

Custom Tool Implementation — In-Process MCP Server

Agent SDK's key feature is the 'in-process MCP server' functionality that registers Python functions directly as tools—no external process required: ```python from claude_agent_sdk import Tool def check_test_coverage(path: str) -> dict: """Calculate test coverage for a given file.""" # Implementation using pytest-cov, etc. coverage = calculate_coverage(path) return {"coverage_percent": coverage, "status": "pass" if coverage > 80 else "fail"} coverage_tool = Tool( name="check_test_coverage", description="Calculate test coverage percentage for a source file", input_schema={ "type": "object", "properties": {"path": {"type": "string"}}, "required": ["path"] }, function=check_test_coverage ) client = ClaudeSDKClient() result = client.query( "Check test coverage for all files in src/", tools=[coverage_tool] ) ``` The agent can use the `check_test_coverage` tool just like standard Claude Code tools. A SaaS company in Shinagawa has implemented 20+ custom tools via Agent SDK: internal database query tools, deployment status checkers, customer data aggregation tools, and more.

Hook Definition — Lifecycle Control with Python Functions

Agent SDK allows defining Hooks similarly as Python functions: ```python from claude_agent_sdk import Hook def validate_before_commit(context): """Run validation checks before git commit.""" if "git commit" in context.tool_input: # lint check result = subprocess.run(["npm", "run", "lint"], capture_output=True) if result.returncode != 0: return {"allow": False, "message": "Lint check failed. Fix errors before committing."} return {"allow": True} commit_hook = Hook( event="PreToolUse", tool="Bash", function=validate_before_commit ) client = ClaudeSDKClient() result = client.query( "Implement feature X and commit", hooks=[commit_hook] ) ``` Python-implemented Hooks enable advanced operations difficult with shell commands: complex conditional logic, external API integration, database logging, etc. A Shibuya development team implemented a Hook that automatically sends all commit information to Slack and Jira.

Sub-Agent Utilization — Context Isolation via Task Tool

Agent SDK can generate **sub-agents** through the `Task` tool. Sub-agents operate in independent contexts and can run in parallel with parent agents: ```python from claude_agent_sdk import ClaudeSDKClient client = ClaudeSDKClient() # Parent agent result = client.query(""" Review this pull request: 1. Create a sub-agent to analyze code quality 2. Create another sub-agent to check security vulnerabilities 3. Aggregate results and generate a summary report """) ``` The agent determines to 'Use the Task tool to create sub-agents for code quality and security analysis' from the prompt, automatically launching two sub-agents. Each sub-agent focuses on specialized tasks and returns results to the parent. **Sub-agent advantages**: - Context window isolation (avoids token limits even in large projects) - Acceleration through parallel execution - Improved task quality through specialization A FinTech company in Minato ward runs four sub-agents in parallel—code review, security audit, performance testing, and documentation generation—reducing PR review time to 1/4 of the original.

Multi-Agent Orchestration — Lead Agent + Worker Architecture

For complex workflows, an 'orchestration pattern' where a **lead agent** divides tasks and distributes them to multiple **worker agents** is effective: ```python from claude_agent_sdk import ClaudeSDKClient import asyncio async def orchestrate_migration(): lead = ClaudeSDKClient() # Lead agent divides tasks plan = await lead.query(""" Plan migration from MongoDB to PostgreSQL: 1. Analyze schema 2. Generate migration scripts 3. Create test fixtures 4. Write documentation Output: JSON task list """) tasks = parse_tasks(plan["output"]) # Launch worker agents in parallel workers = [ClaudeSDKClient() for _ in tasks] results = await asyncio.gather(*[ worker.query(task["prompt"]) for worker, task in zip(workers, tasks) ]) # Merge results final = await lead.query(f"Aggregate results: {results}") return final result = asyncio.run(orchestrate_migration()) ``` This pattern excels in scenarios requiring coordination of 'multiple independent sub-tasks': large-scale refactoring, cross-microservice consistency checks, bulk updates across multiple repositories. A platform company in Shinagawa implemented an orchestrator using Agent SDK for bulk API specification updates across 20 microservices.

Permission Management and Security — Permission Modes and Sandboxing

Agent SDK supports three permission modes: **1. interactive (default)** - Displays confirmation prompts for dangerous operations **2. restricted** - Blocks all operations not on pre-approval list **3. autonomous** - Auto-approves all operations (trusted environments only) ```python client = ClaudeSDKClient(permission_mode="restricted") client.add_allowed_commands(["npm test", "git status"]) ``` Furthermore, Agent SDK provides **sandboxing** functionality (macOS: Seatbelt, Linux: bubblewrap): ```python client = ClaudeSDKClient( sandbox=True, allowed_paths=["/project/src", "/project/tests"], blocked_network=True ) ``` This prevents agents from accessing paths outside specified directories, network communication, and system command execution. A security company in Shibuya mandates sandboxing for all third-party plugin execution.

CI/CD Pipeline Integration — Using Agent SDK in GitHub Actions

Agent SDK excels in CI/CD environments. GitHub Actions example: ```yaml name: AI Code Review on: pull_request: types: [opened, synchronize] jobs: ai-review: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: python-version: '3.11' - run: pip install claude-agent-sdk - name: Run AI review env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} run: | python scripts/ai_reviewer.py --pr ${{ github.event.pull_request.number }} ``` `ai_reviewer.py` implementation: ```python from claude_agent_sdk import ClaudeSDKClient import os pr_number = os.environ["PR_NUMBER"] client = ClaudeSDKClient(permission_mode="restricted") result = client.query(f""" Review PR #{pr_number}: 1. Check code quality 2. Identify security issues 3. Suggest improvements Post review comments via GitHub API """) ``` A SaaS company in Minato ward implemented automated reviews for all PRs with this pattern, allowing human reviewers to focus on 'validating AI-identified issues.' Review time reduced by an average of 60%.

Practical Example: Code Review Agent — PR Diff Analysis and Fix Suggestions

Implementation example of a practical code review agent: ```python from claude_agent_sdk import ClaudeSDKClient, Tool import subprocess import json def get_pr_diff(pr_number: int) -> str: """Fetch PR diff from GitHub.""" result = subprocess.run( ["gh", "pr", "diff", str(pr_number)], capture_output=True, text=True ) return result.stdout def post_review_comment(pr_number: int, body: str, path: str, line: int): """Post review comment to GitHub PR.""" subprocess.run([ "gh", "pr", "review", str(pr_number), "--comment", "--body", body, "--path", path, "--line", str(line) ]) gh_tools = [ Tool(name="get_pr_diff", function=get_pr_diff, ...), Tool(name="post_review_comment", function=post_review_comment, ...) ] client = ClaudeSDKClient() result = client.query( f"Review PR #{pr_number}. For each issue found, post a review comment with specific line references and improvement suggestions.", tools=gh_tools ) ``` This agent executes completely automatically: fetch PR diff → identify issues → post comments on relevant lines. A development team in Shinagawa reports 90%+ detection accuracy for 'variable name typos,' 'unused imports,' and 'insufficient error handling.'

Practical Example: Documentation Generation Agent — Auto-Generate API Specs from Code

Implementation for auto-generating API specifications using Agent SDK: ```python from claude_agent_sdk import ClaudeSDKClient client = ClaudeSDKClient() result = client.query(""" Analyze all API endpoints in src/api/ and generate OpenAPI 3.0 specification: 1. Extract route definitions, parameters, response types 2. Read JSDoc/docstrings for descriptions 3. Generate openapi.yaml with complete schemas 4. Validate the generated spec """) if result["success"]: print("API documentation generated at docs/openapi.yaml") ``` The agent automatically executes: - Search all API endpoint files (Glob) - Read each file (Read) - Extract route definitions and parameters - Generate OpenAPI specification (Write) - Validate specification (Bash: openapi-validator) An API development team in Shibuya runs this agent in CI/CD with every code change, keeping documentation always up-to-date. The 'forgot to update documentation' problem completely eliminated.

Enterprise Adoption and Oflight Support

Enterprise Agent SDK deployment requires these elements: **1. SSO/SCIM Integration** - Anthropic's enterprise plan supports SSO/SCIM with Okta, Azure AD, etc. Automation agents created with Agent SDK can be managed under the same authentication infrastructure. **2. Audit Logging** - Standard implementation for sending all agent execution audit logs to CloudWatch, Datadog, etc. **3. Cost Management** - Token usage tracking per agent. Automatic shutdown mechanism on budget overruns. **4. Shared Team Agent Library** - Libraryization of reusable agents company-wide for sharing across all teams. Oflight Inc. in Shinagawa and Minato wards provides comprehensive support for building enterprise AI development environments using Agent SDK. From custom tool design, multi-agent architecture design, security configuration, to CI/CD integration—we provide consistent support from deployment through operations.

Conclusion — AI-First Development Environment with Agent SDK

Claude Code Agent SDK makes the future of 'embedding AI agents as development tools' a reality. Integration with business systems through custom tools, distributed processing of complex tasks via multi-agent systems, continuous automation through CI/CD pipeline embedding—all achievable with just Python knowledge. Companies in Shinagawa, Minato, and Shibuya wards considering AI development environment adoption using Agent SDK should consult Oflight Inc. Our experienced engineers accelerate your AI utilization—from prototype development to production operations and team training.