feat(agents): implement Anthropic Managed Agents API (v1alpha)

[cdoern]

Summary

Implements the Anthropic Managed Agents API (v1alpha) for agent configuration management. This provides a compatibility layer allowing users to switch from Anthropic's hosted service to Llama Stack without changing their code.

What's Implemented

Agent Configuration CRUD API (/v1alpha/agents)

• ✅ POST /agents - Create agent with model, name, system prompt, tools, skills, metadata
• ✅ GET /agents - List agents with pagination and filtering
• ✅ GET /agents/{id} - Retrieve agent by ID
• ✅ POST /agents/{id} - Update agent (creates new version)
• ✅ POST /agents/{id}/archive - Archive agent

Anthropic Tool Types Supported

1. agent_toolset_20260401 - Built-in tools (bash, edit, read, write, glob, grep, web_fetch, web_search)
   • Per-tool enable/disable and permission policies (always_allow vs always_ask)
2. mcp_toolset - Tools from MCP servers
   • Per-tool configuration with default policies
3. custom - Custom function tools with JSON Schema
   • Client-executed via agent.custom_tool_use events

Key Features

• RFC 3339 timestamps (created_at, updated_at, archived_at)
• Immutable versioning (version increments on update)
• In-memory storage with version history tracking
• Full Anthropic API spec compatibility

Architecture: Responses API as Execution Backend

This implementation follows Anthropic's actual Managed Agents API specification from https://platform.claude.com/docs/en/api/beta/agents/create

Agent configs are stateless templates. The actual execution flow will work as follows:

1. Agent CRUD (this PR) - Store agent configurations with tools defined in Anthropic format
2. Sessions API (future) - Binds an agent to a Responses API conversation
   • Creates a Responses API conversation when session starts
   • Chains turns via previous_response_id
3. Tool Mapping (future) - Translates Anthropic tools → Responses API format:
   • agent_toolset_20260401.web_search → Responses API web_search (uses brave/tavily tool_runtime)
   • agent_toolset_20260401.bash/edit/read/write/etc → function tools (client-executed)
   • mcp_toolset → Responses API mcp tools
   • custom → Responses API function tools
4. Events API (future) - Transforms Responses API SSE → Anthropic event format
   • Responses API streams (text deltas, tool calls) → Anthropic events (agent.message, agent.custom_tool_use)

Key insight: By delegating to the Responses API, we leverage all existing Llama Stack infrastructure:

• Inference providers (vLLM, OpenAI, Azure, Bedrock, etc.)
• Tool execution via tool_runtime (web search, MCP, file search)
• Vector stores for RAG
• Safety shields

The Agents API is a compatibility and orchestration layer, not a reimplementation of agentic behavior.

Testing

Integration tests: tests/integration/agents_anthropic/

• ✅ 18 tests passing (all CRUD operations, tools, MCP servers, skills, pagination, filtering)
• ✅ Anthropic SDK compatibility tests (skipped until SDK adds beta.agents support)

Run tests:

./scripts/integration-tests.sh --stack-config server:ci-tests --subdirs agents_anthropic --setup vllm

Future Work

To complete full Anthropic Agent SDK support:

• Sessions API - Session management with Responses API conversation backing
• Events API - SSE event streaming with format transformation
• Tool Orchestration - Anthropic → Responses API tool mapping
• Environments API - Isolated execution contexts

Breaking Changes

None - this is a new v1alpha API.

Checklist

• Pre-commit hooks pass
• Integration tests pass (18/18)
• OpenAPI specs regenerated
• Provider registry updated
• Distribution configs updated (starter, ci-tests)
• Matches Anthropic API specification

[github-actions]

✱ Stainless preview builds

This PR will update the llama-stack-client SDKs with the following commit message.

feat(agents): implement Anthropic Managed Agents API (v1alpha)

Edit this comment to update it. It will appear in the SDK's changelogs.

✅ llama-stack-client-go studio · conflict

Your SDK build had at least one new note diagnostic, which is a regression from the base state.

New diagnostics (5 note)

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `get /v1alpha/agents`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /v1alpha/agents`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `get /v1alpha/agents/{agent_id}`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /v1alpha/agents/{agent_id}`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /v1alpha/agents/{agent_id}/archive`

✅ llama-stack-client-node studio · conflict

Your SDK build had at least one new note diagnostic, which is a regression from the base state.

New diagnostics (5 note)

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `get /v1alpha/agents`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /v1alpha/agents`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `get /v1alpha/agents/{agent_id}`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /v1alpha/agents/{agent_id}`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /v1alpha/agents/{agent_id}/archive`

✅ llama-stack-client-python studio · conflict

Your SDK build had at least one new note diagnostic, which is a regression from the base state.

New diagnostics (5 note)

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `get /v1alpha/agents`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /v1alpha/agents`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `get /v1alpha/agents/{agent_id}`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /v1alpha/agents/{agent_id}`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /v1alpha/agents/{agent_id}/archive`

✅ llama-stack-client-openapi studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️

New diagnostics (5 note)

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `get /v1alpha/agents`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /v1alpha/agents`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `get /v1alpha/agents/{agent_id}`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /v1alpha/agents/{agent_id}`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /v1alpha/agents/{agent_id}/archive`

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-04-14 14:29:53 UTC

[0xbrainkid]

The Anthropic Managed Agents API compatibility layer is useful for migration without code changes, and the immutable versioning (version increments on update) is the right design — agents should have auditable version histories, not mutable state.

One dimension the current implementation leaves open: agent identity persistence across versions. When POST /agents/{id} creates a new version, the agent gets a new internal state but presumably the same external ID. From a trust perspective, version 1 and version 2 of the same agent ID may have meaningfully different behavioral characteristics (different system prompt, different tool access, different model). A consumer that cached a trust score for agent ID xyz based on version 1 behavior may be misled when version 2 has different capabilities.

A few additions that would make the versioning model trust-aware:

1. Version field in agent card / trust attestation. When an agent registers with AgentFolio or SATP, the attestation should include the specific version it was evaluated at. Trust scores should be version-qualified: trust_score(agent_id=xyz, version=3) = 0.88.

2. Version change event on archive/update. When an agent is archived or updated, downstream systems that hold trust attestations for the old version should be notified that the attestation may be stale. The archived_at timestamp is a good signal, but an explicit version-change event makes this automatable.

3. RFC 3339 timestamps for temporal trust decay. The created_at and updated_at fields are already there — these are the anchors for trust score temporal decay. A trust score earned 6 months ago on version 1 decays to zero if the agent has since been updated twice and archived once.