Support for Stateful Agents

[matoushavlena]

Motivation

Supporting both stateless and stateful agents enables ACP to handle a broader range of use cases, particularly complex or long-lived interactions requiring persistent context. Such agents can offer more natural, efficient, and sophisticated user experiences. The following are some agent examples:

• aider: Agent designed for collaborative AI-assisted programming with integrated file system support.
• supervisor: A long-lived agent managing multi-step tasks.
• Interactive agents involving continuous human-agent interactions while maintaining conversational context.

Stateless vs Stateful Agents

Area	Stateless Agents	Stateful Agents
Scalability and load balancing	✅ Easy	❌ Difficult
Complexity of interaction	❌ Low	✅ High
Communication efficiency	❌ Low	✅ High (incremental changes)
Failure, interruption recovery	✅ Easy	❌ Difficult
Agent complexity	✅ Low	❌ High (state management)

Problem

ACP in Pre-alpha supports both stateful and stateless agents. Stateful agents utilize agent templates, but this feature is currently undocumented. The transport mechanisms (e.g., SSE, WebSockets) inherently maintain stateful connections, raising questions about the adequacy and clarity of the existing implementation. This implementation must be clearly evaluated and documented.

Selecting appropriate transport mechanisms is critical. Incorporating stateful behavior should not overly complicate ACP nor compromise its scalability and performance.

Current Stateless Implementation

The agent author provides a single method to instantiate, run, and destroy an agent:

{
  "id": "msg-001",
  "jsonrpc": "2.0",
  "method": "agents/run",
  "params": {
    "name": "agent-name",
    "input": { "prompt": "Hello world" }
  }
}

Current Stateful Implementation

The agent author provides three separate methods: create, run and destroy of an agent. The create method returns an instance ID, generated by the agent provider. The run method can be called repeatedly.

Create:

{
  "id": "msg-001",
  "jsonrpc": "2.0",
  "method": "agents/create",
  "params": { "templateName": "agent-name", "config": {} }
}

Run:

{
  "id": "msg-002",
  "jsonrpc": "2.0",
  "method": "agents/run",
  "params": {
    "name": "agent-name-001",
    "input": { "prompt": "Hello world" }
  }
}

Destroy:

{
  "id": "msg-003",
  "jsonrpc": "2.0",
  "method": "agents/destroy",
  "params": { "name": "agent-name-001" }
}

Open Questions

• Is the current stateful implementation (session = agent instance) sufficient for all use cases?
• Is the current stateless implementation well-documented, can statelessness be enforced by design?
• Transport consequences - REST (stateless) vs long-lived SSE (stateful) vs websocket (stateful)? Consider progressive enhancement?
• Should standardized headers or metadata be adopted?
• Mechanisms for restartable or recoverable connections?
• Strategies for automated resource cleanup when stateful agents are no longer in use?
• Provide OOTB support for key-value storage?

Alternative Proposal

Passing sessionId through _meta object.

{
  "id": "msg-001",
  "jsonrpc": "2.0",
  "method": "agents/run",
  "params": {
    "name": "agent-name",
    "input": { "prompt": "Hello world" },
    "_meta": {
      "sessionId": "session-123"
    }
  }
}

Goal

ACP should flexibly support stateful and stateless agents while maintaining simplicity and scalability.

Specifically, ACP should:

• Keep protocol-level statefulness minimal, without requiring persistent state management within the protocol itself.
• Provide standardized mechanisms for agents to optionally manage context and state.
• Delegate responsibility for persistent state management and resource cleanup explicitly to agent implementations.

Additional Resources

• Langgraph - Persistence
• Llama stack - Agents API
• MCP discussion - State, and long-lived vs. short-lived connections

Call to action

• Review current implementation and discuss recommended approach to statefulness.
• Discuss transport mechanisms (REST, SSE, WebSockets) and their implications for statefulness.

[pilartomas]

ACP currently supports both stateful and stateless agents. Stateful agents utilize agent templates, but this feature is currently undocumented. The transport mechanisms (e.g., SSE, WebSockets) inherently maintain stateful connections, raising questions about the adequacy and clarity of the existing implementation. This implementation must be clearly evaluated and documented.
Selecting appropriate transport mechanisms is critical. Incorporating stateful behavior should not overly complicate ACP nor compromise its scalability and performance.

I don't think this statement holds exactly true. Appropriate transport mechanism must be used and that is indeed critical but statefulness/statelessness of the agents layer has little to do with it. One can achieve stateful agents even with a simple REST API.

[pilartomas]

Comparing current (template) with the alternative (session) approach. They are quite identical in many aspects:

• Not supplying session id is ekvivalent to calling create agent from template
• Supplying session id is ekvivalent to simple run
• Implementation burden (creation and cleanup) is still fully on the agent implementation.
• Implementation seems to be less bounded on the first glance but I'd say it is almost the same.
• The only thing missing in the alternative is WHEN to perform destruction.

I personally like the alternative approach better since it fairly simplifies the protocol. However, we must figure out the destruction mechanism.

[pilartomas]

Shifting gears a bit. Up until now we were mostly thinking (at least I was) about user-managed stateful agents. What about agent-managed stateful agents?

• Would they work better with explicit create, sessionId or agent as a tool interface?
• If they failed to destroy the created agents explicitly, who would?
• Should they be able to somehow interact with the internal state of another agent? (That holds true for users as well)

As an example, we could make memory as a standalone ACP feature. Stateful agents could be instantiated with a reference to such memory (now a simple sessionId starts to break down a bit). It would then be possible to interact with the memory between agent runs.

[pilartomas]

I skimmed through the modelcontextprotocol/modelcontextprotocol#102 so here are my two cents.

The problem statement is as follows:

This is fairly limiting for serverless deployments, which frequently autoscale up and down, and generally aren't designed around long-lived requests (for example, typically there's a max request lifetime measured in minutes).
Deploying to a Platform-as-a-Service is really nice and convenient as a developer, so not being very compatible with this model creates an impediment to broader MCP adoption.

Basically saying that stateful connections are problems for replication and load balancing.

I'd say we have to ask ourselves if these two things are desirable for the ACP. Should it be made to handle thousands of connections? In a P2P setup, this probably won't be the case. Also, such horizontal scaling would complicate not only transport but also agent implementation, moving in the direction of something quite complex (like a job-backed service with redis as centralized authority) to ensure consistency across load balancing.

[bjornslib]

These are important questions to tackle. Using websocket feels like the natural choice to me for supporting agent-to-agent communication in a safe, reliable and efficient manner. It also follows the MCP standard.

Whether agent communication requires statefullness would depend on the use case. There may or may not be a need for the receiving agent to have data available to them for performing their actions. And there might be a need for the requesting agent to know of the state of the other agent.

I don't think that session ID sufficiently captures the requirements of what kind of states agents need to be aware of each other? This could well be a requirement if using simple REST calls, because the communication exchange is by its very definition stateless and requires an "injection" of state, whereas Websocket establishes a realtime communication channel.

In summary, I think that we should add more examples of the type of states agents might have to be aware of, use Websocket and request/confirm the type of states to be exchanged when establishing the connection.

Food for thought!

[matoushavlena]

Thank you @pilartomas and @bjornslib for the discussion. The latest draft of ACP Alpha spec moved towards REST for the transport (eventually with SSE support for streaming). While websockets are still on our radar (and might be a natural evolution in terms of progressive enhancement), we believe that the protocol should start with the simplest and most scalable transport, which is stateless request-response. Statefulness would be supported through session_id (either passed in payload or header). The full duplex communication is something we can plan on supporting when practical requirements emerge.

[psschwei]

Do we need to think about multi-tenancy here?

For example, in a multi-agent system where agents A and B are both communicating with Z:

graph TD;
A<-->Z;
B<-->Z;

Loading

Do we have safeguards baked in to prevent Z from telling B about A?

Or would we need to run separate instances of Z to prevent leakage, something like:

graph TD;
A<-->Z1;
B<-->Z2;

Loading

[matoushavlena]

Given that the new version of ACP has separated from BeeAI Platform and now includes a support for stateful agents, I think it's fair to close this discussion. Feel free to reopen in ACP's repo: https://github.com/i-am-bee/acp/discussions. New docs site for ACP is available here: https://agentcommunicationprotocol.dev.