Foundations of Claude Orchestration

1. Setting Up the Messages API (Stateless Design)

The Claude API is stateless, it does not persist history between calls. To build a conversation, you must maintain a local array of messages and send the full history back to the API with every request.

Implementation Task: Local Message History

Start by initializing your conversation locally. This lets you build a "synthetic" conversation by manually appending turns.

import anthropic

client = anthropic.Anthropic()

# Start with your local message history
messages = [
    {"role": "user", "content": "Analyze the target audience for an AI consulting firm."}
]

# Create the first request
# Note: Adaptive thinking is required for Opus 4.7
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    thinking={"type": "adaptive"},  # Required for Opus 4.7; replaces budget_tokens
    inference_geo="us",              # Restrict compute to US infrastructure (1.1x pricing)
    messages=messages
)

# Build the synthetic conversation locally by adding the assistant's response
messages.append({"role": "assistant", "content": response.content})

# Add a manual follow-up to the local history
messages.append({"role": "user", "content": "Now, generate three LinkedIn post ideas for this audience."})

2. Creating a Managed Agent

While the Messages API is great for one-off tasks, a Managed Agent is a reusable, versioned resource that bundles the model, persona, and tools into a single ID, essential for scaling production workflows.

Implementation Task: Define the Strategist Agent

Use the agents attribute to create your configuration.

# Create a reusable agent configuration
agent = client.beta.agents.create(
    name="Marketing Strategist",
    model="claude-opus-4-7",
    description="Specializes in high-value lead generation and content strategy.",
    system="You are an expert Marketing Strategist. Use thinking to ensure your plans are data-driven.",
    tools=[
        {
            "type": "agent_toolset_20260401",
            "configs": [
                {"name": "web_search", "enabled": True, "permission_policy": {"type": "always_allow"}},
                {"name": "web_fetch", "enabled": True, "permission_policy": {"type": "always_allow"}}
            ]
        }
    ]
)

print(f"Agent Created: {agent.id} (Version: {agent.version})")

3. Data Residency & ZDR Eligibility

The inference_geo parameter controls where model computation runs on a per-request basis.

• "us", Inference is restricted to US-based infrastructure only.
• "global", Default. Runs in any available geography for best performance.

4. Orchestration Pattern: The Agentic Loop

For the exam, you must understand that the stop_reason field determines the loop's behavior:

• "tool_use", The loop continues. Execute the tool and return the result.
• "end_turn", The loop terminates. This is the only reliable signal that the task is complete.

Lab Exercise: Agent Infrastructure & Loop Control

Objective: implement the core Messages API bookkeeping and reusable agent setup used by the rest of the track.

1. Build a local message history and send a multi-turn request without losing prior assistant content.
2. Create or sketch the reusable agent configuration for the marketing strategist.
3. Implement a loop that branches on stop_reason, continues on tool use, and exits only on end_turn.
4. Add a defensive iteration cap and log a hard failure if the cap stops the run.