Skip to main content

Runtime / Dynamic Configuration Changes

Configure and manage runtime changes to agent state through the AgentStateManager.

Complete Reference

For complete API documentation and event specifications, see agent.yml → Dynamic Changes.

Overview​

AgentStateManager allows safe, validated modifications to the running configuration without restarting your agent.

Example – per-session LLM override​

stateManager.updateLLM(
  { provider: 'openai', model: 'gpt-5', maxInputTokens: 50_000 },
  'user-123'
);

Internally the manager:

  1. Validates the patch against LLMConfigSchema.
  2. Stores the override under sessionOverrides.
  3. Emits state:changed and session:override-set events.

Example – add MCP server at runtime​

await agent.addMcpServer('git', {
  command: 'mcp-git',
  args: ['--repo', process.cwd()]
});

This triggers mcp:server-added, after which MCPManager connects and refreshes its capability cache.

See Also​