feat(claude-agent-sdk): add Claude Agent SDK as a provider

[KennyVaneetvelde]

Summary

Add support for the Claude Agent SDK as a new provider in instructor, enabling structured outputs with the SDK's native JSON schema validation capabilities.

Key Features

• New from_claude_agent_sdk() factory function - Creates an Instructor configured for Claude Agent SDK
• CLAUDE_AGENT_SDK mode - New mode for structured outputs via the SDK
• Automatic schema conversion - Converts Pydantic models to JSON schemas for output_format
• Built-in retry support - Handles validation errors with context-aware retries
• Message format conversion - Automatically converts instructor's message format to prompts

Usage Example

from instructor import from_claude_agent_sdk
from pydantic import BaseModel
import anyio

class User(BaseModel):
  name: str
  age: int

async def main():
  client = from_claude_agent_sdk()

user = await client.create(
  response_model=User,
  messages=[{"role": "user", "content": "Extract: John is 25 years old"}]
)
print(f"Name: {user.name}, Age: {user.age}")

anyio.run(main)

Files Added/Modified

New files:

• instructor/providers/claude_agent_sdk/__init__.py
• instructor/providers/claude_agent_sdk/client.py
• instructor/providers/claude_agent_sdk/utils.py
• examples/claude_agent_sdk/run.py
• docs/integrations/claude_agent_sdk.md

Modified files:

• instructor/__init__.py - Conditional import when claude_agent_sdk is available
• instructor/mode.py - Added CLAUDE_AGENT_SDK mode
• instructor/utils/providers.py - Added CLAUDE_AGENT_SDK provider
• instructor/processing/response.py - Added handler mappings

Benefits

• Uses the Claude Agent SDK's native JSON schema validation for guaranteed compliance
• Familiar instructor interface for existing users
• No subprocess overhead (unlike CLI-based approaches)
• Production-ready with proper error handling and retries

Fixes #1640

---

Adds Claude Agent SDK as a new provider to the instructor framework, enabling structured outputs with JSON schema validation.

• Behavior:
  • Adds from_claude_agent_sdk() factory function in client.py to create an Instructor for Claude Agent SDK.
  • Introduces CLAUDE_AGENT_SDK mode in mode.py for structured outputs.
  • Implements automatic schema conversion from Pydantic models to JSON schemas.
  • Includes built-in retry support for validation errors.
  • Converts instructor's message format to prompts automatically.
• Files:
  • Adds instructor/providers/claude_agent_sdk/__init__.py, client.py, and utils.py for Claude Agent SDK integration.
  • Modifies instructor/__init__.py for conditional import of from_claude_agent_sdk.
  • Updates instructor/processing/response.py to include handler mappings for Claude Agent SDK.
• Documentation and Examples:
  • Adds docs/integrations/claude_agent_sdk.md for integration guide.
  • Provides examples/claude_agent_sdk/run.py for usage examples.
• Misc:
  • Adds CLAUDE_AGENT_SDK to Provider enum in providers.py.

^{This description was created by for 49d9d6f. You can customize this summary. It will automatically update as commits are pushed.}

[ellipsis-dev]

Important

Looks good to me! 👍

Reviewed everything up to 49d9d6f in 1 minute and 7 seconds. Click for details.

• Reviewed 905 lines of code in 9 files
• Skipped 0 files when reviewing.
• Skipped posting 3 draft comments. View those below.
• Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.

1. instructor/providers/claude_agent_sdk/client.py:147

• Draft comment:
  When appending error context to the prompt for retries (lines 147-152), consider the potential for the prompt to grow significantly in length if many retries occur. It may be useful to implement a limit or log a warning if the prompt becomes too long.
• Reason this comment was not posted:
  Confidence changes required: 80% <= threshold 85% None

2. instructor/providers/claude_agent_sdk/client.py:140

• Draft comment:
  The validated model has a dynamic attribute _raw_response attached. Make sure that the response model permits such attribute assignment (e.g. if using frozen models) or document this behavior for clarity.
• Reason this comment was not posted:
  Confidence changes required: 70% <= threshold 85% None

3. instructor/providers/claude_agent_sdk/client.py:110

• Draft comment:
  The code uses actual_model.model_json_schema() for schema conversion. Ensure that the Pydantic model implements this method (pydantic v2) and document version requirements if supporting older versions.
• Reason this comment was not posted:
  Comment did not seem useful. Confidence is useful = 30% <= threshold 85% The comment is asking the author to ensure that a method is implemented and to document version requirements. This violates the rule against asking the author to ensure behavior or document version requirements. However, it does point out a potential issue with version compatibility, which could be useful if rephrased to suggest checking compatibility or updating documentation if necessary.

Workflow ID: wflow_eT8xfOXEW4LxgsHl

^{You can customize by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.}

[KennyVaneetvelde]

Seems like the @ellipsis has not (yet) updated the description but it is no longer async-only now

EDIT: now it has

[KennyVaneetvelde]

@jxnl Any chance to get a review on this? I'd love to integrate Claude Code SDK with Atomic Agents, which requires it to be integrated in Instructor.

Perhaps a good future concept would be to make these clients more pluggable?

[KennyVaneetvelde]

@jxnl What is stopping us from integrating this PR, currently? Would really love to start using this client in Instructor!

[jxnl]

sorry, job interviews....

back on this, shuold be in the jan 7th release

[KennyVaneetvelde]

Wonderful! Happy holidays!