Skip to main content

Chapter 64: The Claude API — Agentic Loops, Structured Output & Batch Processing

Every agent SDK is an abstraction over the Claude API's messages endpoint. Understanding the raw API — stop_reason, tool_use, tool_choice, JSON schemas, and the Batch API — gives you the ability to diagnose any agent behavior, design custom orchestration that SDKs don't support, and make cost/latency tradeoffs that production systems require.

What You'll Learn​

By the end of this chapter, you'll be able to:

  • Construct raw Messages API requests and parse responses (content blocks, stop_reason values)
  • Define tools with effective descriptions and handle the tool_use/tool_result conversation loop
  • Build a complete agentic loop that runs autonomously until stop_reason: "end_turn"
  • Control tool selection with tool_choice (auto, any, forced) for multi-step pipelines
  • Enforce structured output via tool_use with JSON Schemas (nullable fields, enum + "other", format rules)
  • Implement validation-retry loops with Pydantic for extraction quality
  • Use the Message Batches API for 50% cost savings on latency-tolerant workloads

Chapter Structure​

  1. The Messages API — Anatomy of a Request and Response — model, max_tokens, system prompt, messages array, content blocks, stop_reason values
  2. Tool Definitions and Tool Use — tool schemas, effective descriptions, tool_use response handling, tool_result format, tool distribution principles
  3. The Agentic Loop — the complete autonomous loop pattern, model-driven decision making, anti-patterns the certification exam tests
  4. tool_choice — Controlling Tool Selection — auto vs any vs forced, multi-step forced selection patterns
  5. Structured Output via tool_use with JSON Schemas — schema design patterns, semantic validation, format normalization
  6. Validation-Retry Loops for Extraction Quality — retry-with-error-feedback, Pydantic integration, when retries succeed vs fail
  7. The Message Batches API — 50% cost savings, 24-hour processing window, failure handling, batch submission frequency

Running Project​

Students build a complete structured data extraction pipeline using raw API calls, progressing from simple extraction to validation-retry to batch processing.

Prerequisites​

  • Chapter 61: Introduction to AI Agents (conceptual foundation)
  • Part 4: Python proficiency (async/await, type hints)
  • Anthropic API key with Claude access

Certification Exam Coverage​

This chapter covers Claude Certified Architect — Foundations exam domains:

  • Domain 1 (27%): Task Statement 1.1 — Agentic loop implementation
  • Domain 4 (20%): Task Statements 4.3, 4.5 — Structured output, batch processing
  • Directly covers Sample Questions 1, 2, 10, 11