> For the complete documentation index, see [llms.txt](https://docs.labs.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.labs.ai/conversations-and-orchestration/managed-agents.md).

# Managed Agents

## Overview

**Managed Agents** is an EDDI feature that provides automatic conversation management, allowing you to trigger agents based on **intents** without manually creating and managing conversation IDs. EDDI handles the conversation lifecycle for you.

### The Problem It Solves

**Without Managed Agents** (manual approach):

1. Your app creates a conversation: `POST /agents/agent123/start`
2. EDDI returns conversation ID: `conv-456`
3. Your app stores this ID
4. Your app sends messages: `POST /agents/conv-456`
5. Your app manages conversation lifecycle

**With Managed Agents** (automatic approach):

1. You define an agent trigger with an intent keyword
2. Your app sends: `POST /agents/managed/weather_help/user123`
3. EDDI automatically:
   * Creates conversation (if none exists for this user/intent)
   * Routes to correct agent
   * Manages conversation state
   * Reuses existing conversation on subsequent calls

### Use Cases

* **Multi-Agent Applications**: Route users to different agents based on intent without tracking conversation IDs
* **Microservices Architecture**: Each service triggers agents by intent, EDDI handles coordination
* **Simplified Integration**: Client apps don't need conversation management logic
* **User-Centric Sessions**: One conversation per user per intent, automatically managed
* **A/B Testing**: Define multiple agents for same intent; EDDI picks one randomly

### Key Concepts

**Intent**: A keyword or phrase that maps to one or more agent deployments

* Example: `"weather_help"` → Weather Agent
* Example: `"order_status"` → Order Tracking Agent
* Example: `"support_technical"` → Technical Support Agent

**Agent Trigger**: Configuration that links an intent to specific agents

**User ID**: Identifies the user; EDDI maintains one conversation per user per intent

### How It Works

```
1. Define Agent Trigger:
   Intent: "weather_help" → Agent: weather-agent-v2 (production)

2. User Requests:
   POST /agents/managed/weather_help/user-123
   {"input": "What's the weather?"}

3. EDDI Logic:
   - Checks if user-123 has active conversation for "weather_help"
   - If NO: Creates new conversation with weather-agent-v2
   - If YES: Continues existing conversation
   - Processes message through agent's lifecycle
   - Returns response

4. Subsequent Requests:
   POST /agents/managed/weather_help/user-123
   {"input": "What about tomorrow?"}
   → Continues same conversation
```

### Benefits

* **Simplified Client Logic**: No conversation ID management needed
* **Intent-Based Routing**: Natural way to organize multi-agent systems
* **Automatic Session Management**: EDDI handles conversation lifecycle
* **Initial Context Support**: Pass context at conversation start
* **Random Agent Selection**: A/B testing or load distribution built-in

## Managed Agents Configuration

This feature allows you to take advantage of **EDDI**'s automatic management of agents. It is possible to avoid creating conversations and managing them yourself—let EDDI handle it.

This acts as a shortcut to directly start a conversation with an agent that covers a specific **intent**.

First, you need to set up a `AgentTrigger`.

## AgentTrigger

### The request model

```javascript
{
  "intent": "string",
  "agentDeployments": [
    {
      "environment": "environment",
      "agentId": "string",
      "initialContext": {
        "additionalProp1": {
          "type": "string",
          "value": ""
        },
        "additionalProp2": {
          "type": "string",
          "value": ""
        },
        "additionalProp3": {
          "type": "string",
          "value": ""
        }
      }
    }
  ]
}
```

### Description of the request model

| Element          | Description                                                                                                                                                                    |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| intent           | (`String`) keyword or phrase (camel case or with '-') that will be used in managed agents to trigger the agents defined in this model                                          |
| agentDeployments | (`Array:`<`AgentDeployment`>) array of `AgentDeployment`. If multiple `agentDeployments` are defined, one will be picked randomly.                                             |
| environment      | (`String`) the environment: `production` (default) or `test`. Legacy values `unrestricted` and `restricted` are accepted and mapped to `production`.                           |
| agentId          | (`String`) the id of the agent that you want to create the agentTrigger for it.                                                                                                |
| initialContext   | (Object) Context handed to the agent at conversation start. Keys map to `Context` objects with `type` and `value` fields. Only applied when the conversation is first created. |

### AgentTrigger API endpoints

| HTTP Method | API Endpoint                                | Request Body        | Response                      |
| ----------- | ------------------------------------------- | ------------------- | ----------------------------- |
| GET         | `/AgentTriggerStore/agenttriggers`          | N/A                 | Array of Agent Trigger models |
| GET         | `/AgentTriggerStore/agenttriggers/{intent}` | N/A                 | Agent Trigger model           |
| POST        | `/AgentTriggerStore/agenttriggers`          | Agent Trigger model | N/A (200)                     |
| PUT         | `/AgentTriggerStore/agenttriggers/{intent}` | Agent Trigger model | N/A (200)                     |
| DELETE      | `/AgentTriggerStore/agenttriggers/{intent}` | N/A                 | N/A (200)                     |

All five require the `eddi-admin` or `eddi-editor` role when authorization is enabled. The list endpoint returns every trigger to a caller who can see all resources; anyone else gets only the triggers whose every target agent they may use. A single trigger routing to an agent the caller may not use answers 404, exactly like an intent that does not exist, so the endpoint cannot be used to discover another team's intents.

**Who may change a trigger.** Creating, updating and deleting a trigger require `EDIT` on every agent it routes to — for an update, on the agents it routes to before *and* after the change. With [workspaces](https://docs.labs.ai/security-and-compliance/workspaces.md) off every editor holds `EDIT` on every agent, so this restricts nothing there. The `intent` in a `PUT` body must match the `{intent}` in the path (or be left out); a mismatch is a `400` — create the new intent and delete the old one to rename. `POST` for an intent that already exists is refused (`409`), never an overwrite. A trigger must route to at least one agent and every deployment must name its `agentId` (else `400`); a stored trigger that routes nowhere can only be changed by an administrator while workspaces are enforced. An update or delete that races a concurrent re-point of the same trigger answers `409` — re-read and retry.

## Triggering a ManagedAgent

To trigger a managed agent you will have to call the following API endpoints.

### API Methods

| HTTP Method | API Endpoint                                        | Request Body | Response                                                                                                                                                |
| ----------- | --------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET         | `/agents/managed/{intent}/{userId}`                 | N/A          | Conversation model                                                                                                                                      |
| POST        | `/agents/managed/{intent}/{userId}`                 | Input model  | Conversation model (query params `returnDetailed`, default `false`, and `returnCurrentStepOnly`, default `true`, as on `POST /agents/{conversationId}`) |
| POST        | `/agents/managed/{intent}/{userId}/endConversation` | N/A          | N/A                                                                                                                                                     |
| GET         | `/agents/managed/{intent}/{userId}/undo`            | N/A          | Boolean                                                                                                                                                 |
| POST        | `/agents/managed/{intent}/{userId}/undo`            | N/A          | N/A                                                                                                                                                     |
| GET         | `/agents/managed/{intent}/{userId}/redo`            | N/A          | Boolean                                                                                                                                                 |
| POST        | `/agents/managed/{intent}/{userId}/redo`            | N/A          | N/A                                                                                                                                                     |

### Description API endpoint required path parameters

| Element   | Description                                                                |
| --------- | -------------------------------------------------------------------------- |
| {intent}​ | (`String`) the label/keyword used originally to point to this AgentTrigger |
| {userId}​ | (`String`) used to specify the user who triggered the conversation         |

### Example *:*

#### 1/Create an AgentTrigger

*Request URL:*

`POST` `http://localhost:7070/AgentTriggerStore/agenttriggers`

*Request Body*

```javascript
{
  "intent": "weather_trigger",
  "agentDeployments": [
    {
      "environment": "production",
      "agentId": "5bf5418c46e0fb000b7636d0",
      "initialContext": {}
    }
  ]
}
```

*Response Body*

`no content`

*Response Code*

`200`

#### 2/Trigger the ManagedAgent

*Request URL:*

`POST` `http://localhost:7070/agents/managed/weather_trigger/myUserId`

*Request Body*

```javascript
{
  "input": "Hello managed agent!",
  "context": {}
}
```

*Response Body*

```javascript
{
  "conversationId": "65f1c0ffee0123456789abcd",
  "agentId": "5bf5418c46e0fb000b7636d0",
  "agentVersion": 10,
  "userId": "myUserId",
  "environment": "production",
  "conversationState": "READY",
  "undoAvailable": true,
  "redoAvailable": false,
  "conversationOutputs": [
    {
      "input": "Hello managed agent!",
      "actions": ["greet"],
      "output": [ { "type": "text", "text": "Hello! How can I help?", "delay": 0 } ]
    }
  ],
  "conversationProperties": {},
  "conversationSteps": [
    {
      "conversationStep": [
        {
          "key": "input:initial",
          "value": "Hello managed agent!",
          "timestamp": 1552869578596,
          "originWorkflowId": "<workflowId>"
        }
      ],
      "timestamp": 1552869578596
    }
  ]
}
```

The response is the same `SimpleConversationMemorySnapshot` that `POST /agents/{conversationId}` returns (abridged here; the actions and output depend entirely on the agent). Undo and redo state is reported as two booleans, `undoAvailable` and `redoAvailable` — the steps an undo removed are kept on the stored conversation (its `redoCache`) and are not part of this response. The `.../undo` and `.../redo` endpoints above act on the user's current managed conversation for the intent. Fields such as `endReason` or the HITL pause fields (`hitlPausedAt`, `hitlPauseType`, `hitlPendingToolCalls`) appear only when they have a value.

*Response Code*

`200`

*Agent not ready*

If no version of the agent is deployed and ready yet (startup, rolling deploy), the managed endpoints that would start a conversation answer `503 Service Unavailable` with `Retry-After: 5`. Retry after that many seconds; no conversation was created. The MCP `chat_managed` tool answers the same case with `"errorCode": "UNAVAILABLE"`.

*Concurrent requests*

Two requests for the same intent and user that both need a new conversation (none exists yet, or the current one has ended) each start one, but only one can be stored as the user's conversation. The other request uses the stored one and ends the conversation it started, so both clients talk to the same conversation. An ended conversation is only ever replaced while the mapping still points at it, so a slower request cannot remove the replacement a faster one has just stored.

### MCP Integration

The same managed conversation functionality is available via the MCP `chat_managed` tool:

```
chat_managed(intent: "weather_trigger", userId: "myUserId", message: "Hello managed agent!")
```

See [MCP Server](https://docs.labs.ai/protocols-and-integration/mcp-server.md) for full tool documentation.
