awslabs / awslabs/agentcore-samples

03-integrations - [Add Claude Agent SDK agentic patterns: Orchestrator-Workers (subagents) and Hooks (tool governance)]

Open
#993 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.