Claude Managed Agents
Connect CopilotKit to a hosted Claude Managed Agent over AG-UI, then render a backend tool call as interactive generative UI.
Claude Managed Agents run Claude agents in Anthropic-hosted environments. Anthropic manages the model runtime and workspace; your app starts sessions, streams their events, and supplies any application-specific tools. This recipe connects one of those hosted agents to a compact CopilotKit chat over AG-UI.
The example is a focused finance assistant. Ask what a recurring investment could grow to and the managed agent calculates in its hosted workspace, calls one backend tool, and CopilotKit renders an interactive growth projection inline. It is adapted from Anthropic's Claude Managed Agents and CopilotKit quickstart, reduced to one interaction that fits a Cookbook pane.
How it works
- A one-time setup script creates a restricted hosted environment and a versioned managed agent.
ManagedAgentsAgentmaps each CopilotKit thread to one Claude Managed Agents session.- The CopilotKit runtime exposes that agent through an AG-UI-compatible SSE endpoint.
- The managed agent calls
show_growth_projectionwith structured numbers. useRenderToolmatches that streamed tool call by name and mounts the React chart in the transcript.
Try it live
Use the suggested prompt, then adjust the contribution and return sliders in the resulting chart.
Prerequisites
- Node.js 22 or newer.
- An Anthropic Console account and API key with Claude Managed Agents access.
- An Anthropic organization with 30-day data retention. The default
claude-fable-5model is unavailable under zero data retention.
Run the example
Clone CopilotKit and enter the standalone showcase:
git clone https://github.com/CopilotKit/CopilotKit.git
cd CopilotKit/examples/showcases/claude-managed-agents
npm install
cp .env.example .envAdd your key to .env:
ANTHROPIC_API_KEY=sk-ant-your_key
# Optional; defaults to claude-fable-5
ANTHROPIC_MODEL=claude-haiku-4-5Provision the persistent environment and managed agent once, then start the server and frontend:
npm run setup
npm run devOpen http://localhost:5173. npm run setup writes the generated resource IDs to the
gitignored agent-ids.json; rerunning it reuses those IDs instead of creating more billable resources. Use
npm run setup -- --force only when you intentionally want a replacement environment and agent.
Try it
Select the suggested prompt or ask:
If I invest $500/month at a 7% annual return, what will I have in 20 years?Claude passes the assumptions to show_growth_projection and keeps its prose short while the chart
carries the result. Move either slider to explore the assumptions without starting another agent run. A
follow-up in the same CopilotKit thread resumes the same managed session and workspace.
The key pieces, in code
The setup script creates long-lived managed resources. The environment blocks outbound hosts, package managers, and MCP servers, while the agent disables its complete built-in toolset. The runtime adds only the focused financial visualization tool when it creates a session:
const environment = await client.beta.environments.create({
name: `financial-assistant-demo-${Date.now().toString(36)}`,
config: {
type: "cloud",
networking: {
type: "limited",
allowed_hosts: [],
allow_package_managers: false,
allow_mcp_servers: false,
},
},
});
const model = process.env.ANTHROPIC_MODEL ?? "claude-fable-5";
const agent = await client.beta.agents.create({
name: "financial-assistant",
model,
system: ASSISTANT_SYSTEM,
tools: [{
type: "agent_toolset_20260401",
default_config: { enabled: false },
}],
});The model is fixed when the managed agent is provisioned. Changing ANTHROPIC_MODEL later does not update that
agent. Run npm run setup -- --force with the new model, then replace the generated environment and agent IDs
wherever the demo is deployed.
At runtime, the AG-UI adapter owns managed-session creation and maps it to the CopilotKit thread. The visual tool
is supplied as a session override, so changing its schema does not require a new managed-agent version.
CopilotSseRuntime is the CopilotKit runtime that streams agent events over SSE.
The adapter requires only the managed agent and environment IDs, while this recipe adds backendTools for the
interactive projection:
import express from "express";
import { CopilotSseRuntime } from "@copilotkit/runtime/v2";
import { createCopilotExpressHandler } from "@copilotkit/runtime/v2/express";
import { ManagedAgentsAgent } from "@ag-ui/claude-managed-agents";
import { financialAssistantTools } from "./financialAssistantTools";
import { loadAgentIds } from "./setup";
const ids = loadAgentIds();
const runtime = new CopilotSseRuntime({
agents: {
"financial-assistant": new ManagedAgentsAgent({
managedAgentId: ids.agentId,
environmentId: ids.environmentId,
backendTools: financialAssistantTools,
}),
},
});
const app = express();
app.use(createCopilotExpressHandler({ runtime, basePath: "/api/copilotkit" }));To keep the public demo bounded, the example also sets turnTimeoutMs to 90 seconds and rejects request bodies
over 256 KB (server/src/runtimeLimits.ts). The adapter already serializes runs per thread.
The single backend tool declares the exact data the UI needs. Its handler only acknowledges the render because the streamed tool call itself is the user-visible result:
export const financialAssistantTools: BackendCustomTool[] = [{
name: "show_growth_projection",
description: "Render an interactive compound-growth chart in the chat.",
parameters: {
type: "object",
properties: {
title: { type: "string" },
initialAmount: { type: "number", minimum: 0 },
monthlyContribution: { type: "number", minimum: 0 },
annualReturnPercent: { type: "number", minimum: 0, maximum: 30 },
years: { type: "integer", minimum: 1, maximum: 50 },
},
required: ["title", "initialAmount", "monthlyContribution", "annualReturnPercent", "years"],
},
handler: () => "Rendered the projection to the user.",
}];CopilotKit matches the AG-UI tool-call events by name with
useRenderTool. The runnable example validates and coerces the streamed
arguments with Zod before mounting the chart:
useRenderTool(
{
name: "show_growth_projection",
parameters: growthSchema,
render: vizRender(
growthSchema,
"Building growth projection…",
GrowthProjection,
),
},
[],
);Deploy it
The example supports a single-process deployment: build the Vite frontend, then let the Express server serve
both web/dist and /api/copilotkit.
npm install && npm run build && npm startSet ANTHROPIC_API_KEY and the two IDs printed by npm run setup:
ANTHROPIC_ENVIRONMENT_ID=env_...
ANTHROPIC_AGENT_ID=agent_...
ALLOWED_ORIGINS=https://your-app.example.comANTHROPIC_MODEL is used by setup, not by the running server. To change models on Railway, reprovision first and
then update ANTHROPIC_ENVIRONMENT_ID and ANTHROPIC_AGENT_ID with the replacement IDs.
Protect the runtime before going public
- Put the runtime behind your application session check before you go to production.
- Scope
ANTHROPIC_API_KEYto a dedicated, non-default Anthropic workspace with a monthly spend limit. - Set
ALLOWED_ORIGINS. The server then rejects requests without the exact matching Origin header. Custom clients can forge that header, so this check is not authentication.
The example has no user authentication, and every message spends your Anthropic API credits. The public demo
also limits runs per IP and per process. See server/src/requestLimits.ts.
The adapter's default session store is in memory. A server restart starts fresh managed sessions, while the
provisioned environment and agent remain reusable. Replace it with a durable SessionStore if thread continuity
must survive deploys or multiple server replicas.
Going further
- Add another focused backend tool and matching
useRenderToolcomponent; the AG-UI transport does not change. - Persist the thread-to-session mapping in your database for multi-instance deployments.
- Add user authentication, quotas, and audit logging before exposing a credit-spending runtime.
- Add AG-UI Streams through CopilotKit Intelligence so each savings scenario becomes a named, persistent conversation whose messages and generated chart reopen across devices.
Get the code
Full source: examples/showcases/claude-managed-agents. The example includes the runtime and frontend.
How is this guide?