contrib: add tool_registry package with AgenticSession support

[lex00]

What was changed

New optional contrib package temporalio[tool-registry] for running LLM tool-calling loops inside Temporal activities.

• ToolRegistry — maps tool names to JSON Schema definitions and handler functions
• run_tool_loop — standalone tool loop, no Temporal worker required
• agentic_session — crash-safe context manager that checkpoints conversation history via activity.heartbeat() on each turn and restores on retry; session survives both activity crashes and provider-side session expiry since state is stored locally
• Built-in Anthropic and OpenAI providers
• MockProvider and ResponseBuilder for unit testing without a live API key
• MCP tool import via ToolRegistry.from_mcp_tools()

Bug fix included

Handler exceptions in the initial implementation were not caught, causing them to propagate out of the activity. All six SDK providers now catch handler errors and feed them back to the model. Anthropic providers additionally set is_error: true on the tool result block (per the Anthropic API spec); OpenAI has no equivalent field.

Why?

Temporal activities are a natural fit for LLM tool-calling loops, but every team reimplements the same boilerplate. This contrib package standardizes the pattern across all six Temporal SDKs.

This is a different layer from openai_agents, google_adk_agents, and langgraph. Those integrations run each model call as a separate Temporal activity using server-side session IDs. tool_registry runs the entire conversation in one activity using local heartbeat state — which survives server-side session expiry and works identically across all six SDKs. Use openai_agents/google_adk_agents/langgraph when you are already using those frameworks; use tool_registry for direct Anthropic/OpenAI calls or cross-SDK portability.

Proposal: temporalio/proposals#107

Checklist

1. Related to: Add ToolRegistry + AgenticSession proposal proposals#107
2. How was this tested: unit tests with MockProvider (no API key required); integration tests against live Anthropic and OpenAI APIs gated on RUN_INTEGRATION_TESTS=1 (skipped by default)
3. Any docs updates needed? Yes — docs.temporal.io update to follow after merge

[CLAassistant]

All committers have signed the CLA.

[0xbrainkid]

The agentic_session context manager is exactly the right abstraction — crash-safe conversation history via heartbeat checkpoints solves the most painful operational problem with long LLM tool loops in Temporal (activity retry losing context).

One addition worth considering for the AgenticSession interface: session-level identity and trust metadata. The session already holds conversation state. If it also holds the agent identity (which agent is running this session) and its behavioral trust score at session start, two things become possible:

1. Trust-gated tool access within the session. If the session knows the agent identity, ToolRegistry.run_tool_loop() can apply per-agent trust thresholds — the same tool is available to a high-trust agent but sandboxed or blocked for a low-trust agent, without needing to re-query the trust registry on every tool call:

async with agentic_session(
    provider=AnthropicProvider(),
    agent_id="fleet-agent-xyz",
    min_tool_trust=0.80  # tools requiring higher trust are blocked for this agent
) as session:
    result = await session.run_tool_loop(registry, messages)

2. Per-session behavioral audit trail. Each heartbeat checkpoint is a natural attestation point — the session state at each checkpoint can include the agent identity alongside the conversation history. If the session is later audited (e.g., for EU AI Act Article 12 compliance), the checkpoints provide a timestamped, crash-survivor record of which agent made which decisions.

The MockProvider and ResponseBuilder pattern is a good design — makes the trust gating testable without a live registry.