Self-managed agents

The frontend provider usually talks to your agents through the runtime: the frontend hits runtimeUrl, the runtime discovers agents from /info, and a proxy forwards every run server-side. But you can also hand the provider AG-UI agent instances directly and skip the runtime for those agents. There are separate production and local-development options, and choosing the right one matters.

Production: self-managed agents#

selfManagedAgents is the supported configuration option for connecting agents you manage yourself, for example an HttpAgent pointing at an AG-UI-compatible backend you own and have already secured:

Each key is the agentId that chat components and frontend agent APIs use to address that agent. Self-managed agents use your transport and your security model. Because the requests don't pass through the CopilotKit runtime, the runtime's server-side auth, middleware, and routing do not apply. Your agent endpoint must authenticate and authorize every request.

Development: local agents#

How they relate#

Both sources feed the same client-side agent registry. When both are supplied they are merged, and selfManagedAgents wins on a key collision:

Supplying agents through either provider option also satisfies the frontend configuration check when at least one local agent is registered.

	selfManagedAgents	Local agents
Intended for	Production, agents you manage	Local dev / prototyping
Auth	Your responsibility	Your responsibility
Runtime middleware / routing	Not applied	Not applied
Precedence on collision	Wins	Overridden by selfManagedAgents

Related#

• Copilot Runtime: the recommended runtime-backed path and its trade-offs compared with direct connections.
• Connect AG-UI agents: the AbstractAgent / HttpAgent interface these options accept.
• Auth: securing agent traffic when you self-manage the connection.