awslabs / awslabs/agentcore-samples
03-integrations - [Add Claude Agent SDK agentic patterns: Orchestrator-Workers (subagents) and Hooks (tool governance)]
- Dominant language
- Python
- Stars
- 3.4k
- Forks
- 1.3k
- Avg merge
- 1d 22h
- Merged PRs (30d)
- 30
Description
## Description
The `claude-agent/` directory currently has two examples:
- `claude-sdk/` — basic agent with 3 modes (basic, options, tools)
- `claude-with-code-interpreter/` — MCP tool integration with Code Interpreter
These cover basic usage but don't demonstrate key Claude Agent SDK features that other frameworks in the repo already showcase (e.g., OpenAI-agents has multi-agent handoff).
## Proposed additions
### 1. `claude-sub-agents/` — Orchestrator-Workers pattern
Demonstrates Claude Agent SDK's native subagent support (`AgentDefinition` + `Task` tool):
- Orchestrator agent delegates to specialized worker subagents
- `code-analyzer` subagent with read-only tools (Read, Grep, Glob)
- `reporter` subagent with write tools (Read, Write)
- Subagents run with isolated context and restricted tools
Maps to Anthropic's recommended [Orchestrator-Workers](https://www.anthropic.com/engineering/building-effective-agents) agentic pattern.
### 2. `claude-hooks/` — Tool governance with hooks
Demonstrates `PreToolUse` and `PostToolUse` hooks:
- `PreToolUse` blocks dangerous Bash commands and writes to system paths
- `PostToolUse` logs structured audit entries for every tool call
- README explains defense-in-depth: SDK hooks for built-in tools + AgentCore Policy for external tools behind Gateway
## Value
- Fills gaps vs other framework examples in the repo
- Showcases Claude Agent SDK features unique to the SDK (subagents, hooks)
- Connects to existing AgentCore Policy tutorials for a complete governance story
- Each example follows the same structure as existing examples (agent.py, Dockerfile, README, requirements.txt)
Contributor guide
Research direction
Start by comparing the existing claude-sdk/ and claude-with-code-interpreter/ examples, including their agent.py, Dockerfile, README, and requirements.txt structure. Then review the Claude Agent SDK documentation for AgentDefinition, Task, PreToolUse, and PostToolUse before adding claude-sub-agents/ and claude-hooks/. Done means both examples demonstrate the requested delegation, tool restrictions, blocking, and audit logging with clear README guidance.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- ai, security
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100