How to Configure Embabel Agent Execution Modes: Focused, Closed, and Open

Configure Embabel agent execution modes by setting embabel.agent.platform.execution-mode to focused, closed, or open in your application.properties, or dynamically switch modes at runtime using the AgentPlatform.setExecutionMode() API.

The Embabel agent framework provides three distinct execution modes that determine how the AgentPlatform routes requests to agents. Whether you need deterministic agent invocation or dynamic intent-based routing, understanding how to configure Embabel agent execution modes is essential for building effective AI applications with the embabel/embabel-agent repository.

Understanding the Three Platform Execution Modes

The ExecutionMode enum in embabel-agent-api/src/main/kotlin/com/embabel/agent/platform/ExecutionMode.kt defines three strategies that control agent selection:

• Focused: Your code explicitly invokes a specific agent with direct input. Ideal for event-driven workflows where the target agent is known at compile time.
• Closed: The platform classifies incoming intent and selects the appropriate agent from a pre-registered pool. Suitable for chat-bot routing or webhook dispatch systems.
• Open: The platform evaluates user intent against all known goals, builds a custom agent on-the-fly, and executes it. This provides maximum flexibility for general-purpose assistants but offers less determinism.

According to the repository README (lines 124-140), these modes represent progressively broader scopes of agent selection autonomy, from explicit developer control to fully autonomous agent generation.

Configuring Global Platform Mode

Using application.properties

Set the execution mode statically via your Spring configuration:

# Options: focused (default), closed, open

embabel.agent.platform.execution-mode=open

If this property is omitted, the platform defaults to Focused mode, requiring explicit agent invocation in your code.

Runtime Configuration

For dynamic switching without restarting the application, obtain the AgentPlatform bean and invoke setExecutionMode():

import com.embabel.agent.platform.AgentPlatform
import com.embabel.agent.platform.ExecutionMode

val platform: AgentPlatform = ApplicationContextProvider.getBean(AgentPlatform::class.java)

// Switch to Closed mode for intent-based routing
platform.setExecutionMode(ExecutionMode.CLOSED)

// Later, enable Open mode for exploratory tasks
platform.setExecutionMode(ExecutionMode.OPEN)

The AgentPlatform interface exposes this method to allow runtime adaptation to different workflow requirements.

Configuring MCP Server Execution Modes

For MCP (Multi-Client Process) server components, execution mode controls whether requests are handled synchronously or asynchronously. The McpExecutionMode enum in embabel-agent-mcp/embabel-agent-mcpserver/src/main/kotlin/com/embabel/agent/mcpserver/domain/Types.kt (line 27) defines two options:

• SYNC: Blocking request handling where the server waits for completion before responding
• ASYNC: Non-blocking request handling allowing concurrent processing

Configuration via Properties

embabel.mcpserver.execution-mode=ASYNC

Programmatic Strategy Selection

You can also instantiate the appropriate strategy implementation directly:

import com.embabel.agent.mcpserver.sync.McpSyncServerStrategy
import com.embabel.agent.mcpserver.async.McpAsyncServerStrategy

val serverStrategy = if (useAsync) {
    McpAsyncServerStrategy()  // Uses McpExecutionMode.ASYNC per line 44
} else {
    McpSyncServerStrategy()   // Uses McpExecutionMode.SYNC per line 43
}

The concrete implementations reside in:

• embabel-agent-mcp/embabel-agent-mcpserver/src/main/kotlin/com/embabel/agent/mcpserver/sync/McpSyncServerStrategy.kt (line 43)
• embabel-agent-mcp/embabel-agent-mcpserver/src/main/kotlin/com/embabel/agent/mcpserver/async/McpAsyncServerStrategy.kt (line 44)

Practical Example: Open Mode Configuration

Here is a complete Kotlin example demonstrating how to configure Embabel agent execution modes programmatically for dynamic agent generation:

import com.embabel.agent.platform.AgentPlatform
import com.embabel.agent.platform.ExecutionMode

fun main() {
    // Obtain the Spring-managed platform instance
    val platform = ApplicationContextProvider.getBean(AgentPlatform::class.java)
    
    // Configure for Open mode to enable on-the-fly agent construction
    platform.setExecutionMode(ExecutionMode.OPEN)
    
    // Execute a natural language request without pre-registering agents
    val result = platform.runAgent("Analyze Q3 sales data and generate insights")
    println(result)
}

In this configuration, the platform analyzes the input intent against all known goals, constructs an appropriate agent dynamically, and executes the task.

Summary

• Three platform modes: Focused (explicit invocation), Closed (intent classification from registered pool), and Open (dynamic agent generation) defined in ExecutionMode.kt
• Configuration methods: Set embabel.agent.platform.execution-mode in application.properties or call AgentPlatform.setExecutionMode() at runtime
• Default behavior: Focused mode when no configuration is provided, ensuring deterministic agent invocation
• MCP server modes: SYNC (blocking) versus ASYNC (non-blocking) controlled via embabel.mcpserver.execution-mode or direct strategy instantiation
• Source locations: Core logic in embabel-agent-api, MCP strategies in embabel-agent-mcp/embabel-agent-mcpserver/src/main/kotlin/com/embabel/agent/mcpserver/

Frequently Asked Questions

What is the default execution mode if I don't configure anything?

If you omit the embabel.agent.platform.execution-mode property, the AgentPlatform defaults to Focused mode. In this mode, you must explicitly specify which agent to invoke via code rather than relying on the platform to classify intents or generate agents dynamically.

Can I switch execution modes without restarting my application?

Yes. While property-based configuration in application.properties requires an application restart, you can switch modes dynamically by calling platform.setExecutionMode(ExecutionMode.CLOSED) or platform.setExecutionMode(ExecutionMode.OPEN) on the AgentPlatform bean obtained from the Spring application context.

When should I use Open mode versus Closed mode?

Use Closed mode when you have a predefined, registered set of agents with specific capabilities and want the platform to classify user intents and route to the best match from that known pool. Use Open mode for exploratory AI tasks or general-purpose assistants where the platform should analyze the user's goal and construct a custom agent on-the-fly, offering maximum flexibility at the cost of predictability.

How do MCP execution modes differ from platform execution modes?

Platform execution modes (Focused, Closed, Open) control which agent handles a request and how it is selected from available options. MCP execution modes (SYNC, ASYNC) control the technical processing model—whether the server blocks the thread until the agent completes (SYNC) or handles the request asynchronously (ASYNC). These operate independently and are configured separately via embabel.mcpserver.execution-mode.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}