Discussion: How should agent configuration be handled in ACP?

[matoushavlena]

We're exploring how to best support agent configuration in ACP, particularly around the Run object and its interaction model.

📦 Current model

Right now, the primary way to interact with an agent is by creating a Run, and the Run takes an input — typically an array of Message objects.

However, in practice, agents often require configuration:

• Choosing a specific LLM model
• Setting parameters like temperature or max tokens
• Enabling/disabling certain tools
• Providing API keys or contextual flags

💡 Ideas on the table

1. Pass config via input (inside message parts)
   Encode structured config as a JSON object in a MessagePart, using extensions if needed.

   Pros:

   • Leverages existing structure, no changes to the protocol
   • Easy to prototype and implement

   Cons:

   • Clients must parse message content to extract config
   • Harder to document, validate, and enforce config schemas
   • Blurs the line between content and configuration

2. Introduce a dedicated config field in Run
   Add a new optional field (e.g. Run.config) to separate config from content.

   Pros:

   • Clear and structured API separation between input and configuration
   • Easier to define, validate, and share JSON schemas
   • Improves tooling and documentation

   Cons:

   • Requires a protocol change (backward compatibility concerns)
   • Slightly more complex for clients to construct

3. Use await to dynamically request configuration
   The agent can issue a MessageAwaitRequest asking the client for configuration data at runtime.

   Pros:

   • Makes config fully dynamic and optional
   • Useful for advanced or interactive agents
   • Reduces initial input requirements for the client

   Cons:

   • Breaks compatibility with non-interactive clients
   • Harder to reason about expected config ahead of time
   • May complicate orchestration or tooling around agents

Each approach has different trade-offs. A shared requirement across all options is the ability for the client to know what configuration is supported or expected.

📘 Agent detail and discoverability

Should configuration metadata/schema be included in the AgentDetail object? For example:

{
  "config_schema": {
    "type": "object",
    "properties": {
      "model": { "type": "string", "enum": ["gpt-4", "mistral"] },
      "temperature": { "type": "number", "default": 0.7 }
    }
  }
}

This would allow client tooling or UI builders to introspect and adapt automatically to what an agent supports.

🔐 Beyond ACP: Environment variables and secrets

Some configuration needs are deployment-level:

• Environment variables (e.g. OPENAI_API_KEY, MODEL_BACKEND)
• Runtime flags and secrets

These are better handled by orchestration platforms like BeeAI, not ACP directly.

🧠 Questions for discussion

• Should config be passed via input, or introduced as a top-level config field?
• Should we use await for optional or runtime configuration?
• How should clients discover and validate supported config options?
• Should AgentDetail include a config_schema?
• Should ACP define best practices or leave some of this up to platforms like BeeAI?

Looking forward to community input on how to evolve this in a way that balances flexibility, interoperability, and simplicity.

[michael-desmond]

@matoushavlena I captured some related thoughts here, specifically around user configurable settings.

1. Separation of configuration and content is generally a smart option so I think that 2. or 3 are more desirable solutions.
2. However for a chat based agent settings could be applied per turn, so having settings as part of the message kind of makes sense there. For instance if you wanted to switch on Thinking mode for a turn, and then switch it off next turn. Of course this could also be handled by just switching on and off a global config, but having configuration embedded in the message would be useful if the user wanted to go back and edit a previous turn because this info would be available in the message history.
3. I think configuration data should be included in the AgentDetail metadata. We did this for Think when communicating settings between the agent and the UI layer.
4. I believe this is an ACP concern.

[matoushavlena]

@michael-desmond Thanks for capturing this! Option 2 seems preferable to me at the moment, as it aligns with separation of concerns (SoC) and allows per-turn configuration changes.

I think we should ensure this:
a. Sensible defaults exist so explicit user configuration isn't always required.
b. Users can adjust settings per turn or leave them unchanged (no-op), maintaining the previous configuration state.
c. Configuration options are included in the Agent Detail metadata. (you already mentioned this)

What do you think?

cc @tomkis @pilartomas

[tomkis]

My two cents;

While i love the concept of leveraging await for configuration i also believe that your point

Harder to reason about expected config ahead of time

Is something i perceive here as a showstoper because building UIs around this will just result in worse UX since UI doesn't know how it looks before it gets the await, hence static information about agent configuration capabilities is mandatory for great UX.

I am also absolutely aligned with SoC for the configuration therefore the 2nd option seems to be more favorable to me.

[michael-desmond]

Hi @matoushavlena, I think this would work well for most use cases that I am aware of.

For the record I was intrigued by the state management system described in ag-ui which is essentially synchornized state between the UI and the running Agent. I think such a system would facilitate interesting interactions, especially for long running or ambient agents.

@tomkis can you give an example of how the await approach would be a showstopper, Im not quite sure I understand but I would like to. Thanks.

[matoushavlena]

@pilartomas Can you look at the state management in ag-ui? Especially in terms of the Distributed Sessions discussion. Wondering what's your take on it.