agent-sdk-definitions

Agent SDK Definitions

For SDK-based applications, agents can be defined programmatically instead of as markdown files.

TypeScript Definition

import { query, ClaudeAgentOptions, AgentDefinition } from "@anthropic-ai/claude-agent-sdk";

const options: ClaudeAgentOptions = {
  // Parent agent needs Task tool to invoke subagents
  allowed_tools: ["Read", "Grep", "Glob", "Edit", "Write", "Bash", "Task"],

  agents: {
    "code-reviewer": {
      description: "Security-focused code reviewer. Use PROACTIVELY for auth code.",
      prompt: `You are a security code reviewer specializing in authentication
and authorization code. You identify vulnerabilities, suggest fixes,
and ensure best practices are followed.

Focus Areas

• Authentication flows
• Session management
• Input validation
• Access control

Output Format

Provide findings as:

1. Severity (Critical/High/Medium/Low)

2. Location (file:line)

3. Issue description

4. Recommended fix`, tools: ["Read", "Grep", "Glob"], // Read-only access model: "opus" },

   "test-runner": { description: "Runs tests and analyzes failures. Use when tests need to be executed.", prompt: You run test suites and analyze failures. You identify root causes and suggest fixes for failing tests., // Omit tools to inherit all from parent model: "sonnet" } } };

// Execute with agents for await (const message of query({ prompt: "Review the authentication module for security issues", options })) { console.log(message); }

## Python Definition

```python
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Grep", "Glob", "Edit", "Write", "Bash", "Task"],

    agents={
        "code-reviewer": AgentDefinition(
            description="Security-focused code reviewer. Use PROACTIVELY for auth code.",
            prompt="""You are a security code reviewer specializing in authentication
and authorization code. You identify vulnerabilities, suggest fixes,
and ensure best practices are followed.

## Focus Areas
- Authentication flows
- Session management
- Input validation
- Access control""",
            tools=["Read", "Grep", "Glob"],
            model="opus"
        ),

        "test-runner": AgentDefinition(
            description="Runs tests and analyzes failures. Use when tests need to be executed.",
            prompt="You run test suites and analyze failures.",
            # tools omitted = inherit all
            model="sonnet"
        )
    }
)

async def main():
    async for message in query(
        prompt="Review the authentication module",
        options=options
    ):
        print(message)

asyncio.run(main())

AgentDefinition Schema

type AgentDefinition = {
  description: string;   // Required: When to invoke (routing key)
  prompt: string;        // Required: System prompt content
  tools?: string[];      // Optional: Allowed tools (omit = inherit all)
  model?: 'sonnet' | 'opus' | 'haiku' | 'inherit';  // Optional: Model override
}

Key Differences from Filesystem Agents

Aspect	Filesystem (.claude/agents/)	SDK (programmatic)
Format	Markdown with YAML frontmatter	TypeScript/Python objects
Loading	Automatic from directory	Passed in options
Prompt	Markdown body	String in prompt field
Use case	Claude Code CLI	Custom SDK applications

When to Use SDK Format

• Building custom agent harnesses
• Programmatic agent orchestration
• Dynamic agent creation at runtime
• CI/CD pipelines with agent tasks
• Applications embedding Claude agents

Providing Both Formats

When a user may use either approach, provide both:

1. Markdown file for .claude/agents/{name}.md
2. SDK definition for programmatic use

This ensures compatibility with both Claude Code CLI and custom SDK applications.