Skip to main content
The agent definition selects the model and core capabilities of a managed deep agent.
Managed Deep Agents is in public beta on LangSmith Cloud and Bring Your Own Cloud (BYOC). Use Managed Deep Agents CLI and SDK v0.10 or later for BYOC.
The agent entry lives at the project root:
You can also use agent.tsx. For the full project layout, see Project structure. To define the agent, use defineDeepAgent:
Configure the system prompt, skills, memory, sandbox, identity, channels, and schedules through their project files rather than the agent definition. See Project structure. To select the system prompt, skills, MCP servers, memory, or sandbox for each run, see Select configuration per run. defineDeepAgent does not compile an agent. It returns a definition, and the managed runtime compiles it with createDeepAgent at deploy time. The options below are the createDeepAgent surface without the ones the runtime owns. See Relationship to Deep Agents.

Parameters

Mount your own backends

routes mounts Deep Agents backends at path prefixes, the same way CompositeBackend routes do. A path under a prefix goes to that backend with the prefix removed. Every other path stays on the managed backend.
routes requires managed-deepagents 0.10.3 or later.
agent.ts
With this route, the agent’s file tools read and write /documents/a.md as /a.md in the store backend.
  • Each prefix must be an absolute directory that starts and ends with /, such as "/documents/".
  • A prefix cannot overlap the paths Managed Deep Agents mounts itself: /instructions.md, /skills/, and /memories/.
  • Routes apply to the file tools only. Shell commands in a sandbox do not see them.

Select configuration per run

To select the agent’s configuration for each run, export a function as agent instead of a definition. One deployment can then adapt to different users, tasks, or repositories. The function is a graph factory, the same pattern LangGraph uses to rebuild a graph at runtime: it receives the runtime and returns a definition. This example selects instructions and skills for the repository a run works on. It assumes the project has skills/python-service/ and skills/typescript-web/, each with a SKILL.md.
agent.ts
The factory can be sync or async. It receives a ManagedServerRuntime, which extends the native LangGraph ServerRuntime. Read run context from executionRuntime.context. It is undefined on channel runs, and executionRuntime is null when Agent Server loads the agent for inspection. Callers choose the configuration through the run’s context:
Run context is application data, not verified identity. Check authorization in tools against the verified caller on the runtime.

Select managed resources

A factory can also select the resources that a static agent reads from project files. Omitting a field keeps the project’s configuration. Providing a value replaces it for that run:
Browser declarations and per-run selection were added in SDK 0.10. Keep a root browser.ts even when the factory selects a browser. See Choose a browser per run.
Static definitions cannot set these fields. A skill path must end in skills/<name> and point to a skill in the project. A factory can also return generated skill definitions, whose names must not duplicate project skill names. This example enables the docs MCP server on request and gives one repository a longer sandbox timeout. It imports the declarations from tools/mcp and sandbox/:
agent.ts
A memory selection overrides the project’s memory declaration for that run. User memory still mounts only for an authenticated person. See Select layers for each run.

Keep the factory repeatable

Managed Deep Agents calls the factory at the start of each run, and again when a run resumes or retries. Agent Server also calls it to read schemas and state. Follow these rules:
  • No side effects: Return the same definition for the same context. Do not create records, call external APIs, or change shared state in the factory.
  • Stable interrupts: Keep middleware that can interrupt a run in every configuration. When a run resumes, the middleware that raised the interrupt must still be present.
  • Inline name: Set name as an inline string. mda build reads it without calling the factory and uses it as the graph ID and default deployment name.
  • Model dependencies: Install the integration package for every model the factory can return. The build does not detect them.
To change behavior between model calls within a run, use custom middleware.

Cache compiled graphs

cachedAgent keeps the graph that a factory compiles and reuses it on later runs with the same parameters. Without it, a factory compiles a new graph on every run, and each run waits for that compile. keyedBy returns the parameters the graph depends on, as a JSON-serializable value. Managed Deep Agents compiles one graph for each distinct value. The factory gets only these parameters, so read per-run data, such as credentials, in tools or middleware.
cachedAgent requires managed-deepagents version 0.10.2 or later.
agent.ts

Use LLM Gateway

You can use LLM Gateway to apply rate limits, fallbacks, and other policies to model calls. Prefix the gateway model ID with langsmith::
Gateway model IDs use a slash between provider and model (langsmith:provider/model-name). Model strings that call a provider directly use a colon (provider:model-name).
The gateway routes each request by model ID. moonshotai/kimi-k3 is a LangChain-hosted model, so it requires no provider secret and draws on Gateway Credits. A model ID that starts with a provider your workspace has configured, such as anthropic/claude-opus-5, uses that provider secret and bills to your own provider account. For more information, see LLM Gateway. To scaffold a project that uses Gateway from the start, pass --gateway when initializing: