@ag-ui/claude-managed-agents

Connect an AG-UI frontend to Claude Managed Agents, Anthropic's hosted agent runtime. Each AG-UI thread maps to one managed session. Each run drives one turn of that session and streams the agent's events back as AG-UI events.

Installation

npm install @ag-ui/claude-managed-agents @anthropic-ai/sdk

Usage

Create a managed agent and an environment once (in the Console, or via the SDK), then wrap them:

import { ManagedAgentsAgent } from "@ag-ui/claude-managed-agents";

const agent = new ManagedAgentsAgent({
  managedAgentId: "agent_...",
  environmentId: "env_...",
});

agent
  .run({ threadId, runId, messages, tools, state, context, forwardedProps })
  .subscribe({
    next: (event) => console.log(event.type),
  });

The Anthropic client reads ANTHROPIC_API_KEY from the environment. Pass client to supply your own.

What it does

Frontend tools (human-in-the-loop)

Tools passed in RunAgentInput.tools are registered on the session as custom tools. When the agent calls one, the run emits the tool call and finishes, leaving the session parked. The client executes the tool and starts the next run with a role: "tool" message carrying toolCallId. The adapter forwards it into the session as the tool result and resumes streaming.

Backend tools

Tools your server executes go in backendTools:

new ManagedAgentsAgent({
  managedAgentId,
  environmentId,
  backendTools: [
    {
      name: "get_weather",
      description: "Get the weather for a location.",
      parameters: {
        type: "object",
        properties: { location: { type: "string" } },
      },
      handler: async (input) => JSON.stringify({ temperature: 21 }),
    },
  ],
});

The tool call and its result stream to the UI, and the result is returned to the agent.

Options

Security: authenticate and bind threads to callers

AG-UI thread IDs are supplied by the client and this agent keys thread↔session state by managedAgentId:threadId, so a thread ID is effectively a bearer identifier: any caller who presents a thread ID resumes that thread's session. The AG-UI protocol carries no user identity of its own, so authorization is your host's responsibility:

• Put the endpoint behind your own authentication. Never expose it unauthenticated.
• RUN_ERROR never relays the text of a failure this integration did not author. An SDK, session-store or API exception can carry session ids, request paths or credentials, so its message goes to onError and the client gets a stable message plus the machine-readable code. Two things are deliberately still verbatim, because they are the point of the event: a session.error from the API (a structured field with its own type code, and the only account of why a session broke) and a backend tool's own exception message (your code, and what the agent needs to recover).
• In multi-tenant deployments, bind threads to the authenticated caller so one caller cannot resume another's session by guessing or replaying a thread ID. Do this with a sessionStore whose keys include the caller identity derived from your auth layer (never from the request body):

The key the agent passes in is already scoped to the managed agent; treat it as an opaque string and prefix it with the caller identity rather than parsing it:

class PerCallerStore implements SessionStore {
  constructor(
    private ownerId: string,
    private inner = new Map<string, SessionRecord>(),
  ) {}
  private scoped = (key: string) => `${this.ownerId}|${key}`;
  get = (key: string) => this.inner.get(this.scoped(key));
  set = (key: string, record: SessionRecord) =>
    void this.inner.set(this.scoped(key), record);
  delete = (key: string) => void this.inner.delete(this.scoped(key));
}

Reuse ONE store instance per caller — construct it once and cache it:

const shared = new Map<string, SessionRecord>();
const stores = new Map<string, PerCallerStore>();
const storeFor = (ownerId: string): PerCallerStore => {
  let store = stores.get(ownerId);
  if (!store)
    stores.set(ownerId, (store = new PerCallerStore(ownerId, shared)));
  return store;
};

Runs are serialized per thread within a store instance, so a fresh wrapper per request would let a double-submitted thread post into the same session twice. Cache the store (as above) and construct the agent with storeFor(ownerId).

Notes

• The default session store is in-memory: restarting the process starts new sessions. Managed sessions themselves persist server-side.
• Turns are serial per thread. A second run on a busy thread errors with code run_in_progress.
• Only the text of a user message is forwarded. A message with image or binary parts and no text errors with code empty_run instead of creating a session.
• When the client disconnects during a fresh turn (or abortRun() is called), the adapter posts user.interrupt to stop the session. Reconnect closes its stream without interrupting the existing session. A turn that exceeds turnTimeoutMs is interrupted the same way and errors. A backend tool handler still running at that point is abandoned and answered with an error so the session is not left parked.
• Built-in tools (bash, file editing, web) execute inside the managed environment. This adapter surfaces them for display, so enable them on your agent as usual.
• Tool-result text blocks reach the UI verbatim: they carry literal output (a file read, a shell transcript), where < means those four characters. Only search_result blocks, whose bodies are extracted from HTML, have their entities decoded.
• A follow-up message posted immediately after a tool result can race the session's asynchronous un-park and be rejected with a 400. That specific rejection is retried, matched on the message containing waiting on responses — wording that has not been confirmed against the live API. If the API rewords it the retry stops firing and the 400 surfaces as a run error; nothing else is affected. See the comment on the matcher.
• The default in-memory store is bounded (IN_MEMORY_SESSION_STORE_MAX_ENTRIES, 10 000 mappings): thread ids are client-supplied, so past that the least-recently-used mapping is evicted and that thread starts a fresh session. Pass a smaller cap to new InMemorySessionStore(n), or supply a persistent store.
• A run that is interrupted — a turn timeout, a client disconnect, or a blocked action this integration cannot answer — forgets the frontend tool calls it had recorded as parked. The interrupt cancels whatever the session was waiting on, so answering one of those calls on the next run would be rejected as stale. If the interrupt itself could not be delivered the ids are kept, since the session may still be parked on them.
• A session that registers custom tools holds a full replacement tool list, frozen at the last update, so the agent's own tools are re-read once per run to catch a Console edit to them. A session with no custom tools runs the agent as-is and skips that read entirely.

Running the examples

cd integrations/claude-managed-agents/typescript
pnpm install
export ANTHROPIC_API_KEY=sk-ant-...   # or ANTHROPIC_AUTH_TOKEN
pnpm setup:examples   # provisions an environment + one agent per Dojo feature (idempotent)
pnpm dev:examples     # http://localhost:8024

Setup writes the provisioned IDs to examples/.managed-agents.json (gitignored). It reuses existing agents by name and does not modify them: to apply prompt or model changes from examples/agents.ts, archive the agent and re-run setup.

The examples default to claude-sonnet-5-5, which supports runtime context via native system messages. MANAGED_AGENTS_MODEL overrides this default; choose a model from the system-injection support list. Existing agents created on Sonnet 5 are not upgraded by changing this variable or rerunning setup. To migrate, archive the old example agents, rerun setup to provision replacements and rewrite the saved IDs, then restart the example server and start new sessions. Existing sessions remain bound to their original agents.

Reconnect existing sessions

Supply a persistent SessionStore to keep the thread/session binding, pending requests and native event cursor across backend restarts. The default store is in memory. Stores must partition records by authenticated caller and serialize runs across replicas; the adapter's in-process lock does not coordinate servers.

For imported sessions, configure resolveSession(threadId) on the server. The callback must authorize the caller's access and return the original binding:

resolveSession: async (threadId) => {
  const imported = await authorizedImports.find(threadId);
  if (!imported) return undefined; // Only for genuinely new conversations.
  return {
    sessionId: imported.sessionId,
    lastUserMessageId: imported.lastUserMessageId,
    lastEventId: imported.lastNativeEventId,
  };
};

authorizedImports represents your authenticated application's durable import mapping, not a client-supplied session selector. Throw for inaccessible or missing imported sessions instead of returning undefined, which permits new-session creation. lastUserMessageId is the last imported AG-UI user message ID; lastEventId is the last native event already saved by the importer. If omitted, initial adoption treats the submitted user history and current native history as already imported. Supplying both boundaries allows the first follow-up and any activity since import to be distinguished from old history.

An empty run reconnects an existing mapping without sending user text. Adopted sessions retain their native tool configuration. Reconnect opens the native stream before listing history, recovers pending calls by their original IDs, and replays activity after the saved event cursor without executing old tools. Terminated or unavailable sessions return an explicit run error and retain their binding; start a new AG-UI thread to create a replacement.

Custom-tool answers use ordinary role: "tool" messages with the original toolCallId. Native tool permissions appear as RUN_FINISHED.outcome interrupts with reason tool-approval; answer with resume: [{ interruptId, status: "resolved", payload: "allow" }] or payload "deny". status: "cancelled" explicitly denies that request. Partial answers leave the other requests pending; a new user message never rejects them.

A binding may include sessionThreadId to inspect and answer a child thread. Native tool IDs route results to the correct child automatically. New user messages must target the primary session; the adapter rejects child follow-ups rather than delivering them to the wrong agent. Other native content replayed as RAW events remains available to the recording application; rendering richer content depends on the application's event handling.