--- url: /agentic-ai/configure-agent.md --- # Configure and use an agent in chat In ALIDA, an endpoint can be exposed for each agent. The BDA chat can be connected to multiple agents through these endpoints by using an environment variable that contains the relevant JSON configuration. Environment variables are set from the [Personalization of Environment Variables](../environment-customization.md) panel. ## What an agent is, and what it is not An agent is an ALIDA *Service*, but not every Service can be used as an agent. A Service is usable as an agent when it has both of these characteristics: * it is **long-running**: it stays up for the whole life of the workflow and keeps answering requests, instead of running once and terminating; * it **exposes REST ports**: an invocation endpoint and, normally, a streaming endpoint, which the chat calls. A normal batch Service, one that reads a dataset, transforms it and terminates, cannot be used as an agent, even though a workflow containing it has a URL. It does not stay running, and it does not speak the chat protocol. The same is true for a workflow that has already finished its execution. The agents currently distributed with ALIDA are the [OpenCode Agent](opencode-agent.md) and the [ADK Agent](adk-agent.md). To use one, put it in a workflow, configure its ports, and start the workflow: the endpoints exist only while that workflow is running. ## How to read the endpoint URL The URL of a running agent looks like this: ```text https://alida.devng.alidalab.it/events/bda/11150/11152/v1 └──────────── instance ───────┘ └─┬─┘ └─┬─┘ └┬┘ │ │ └── protocol suffix, OpenAI only │ └─────── id of the agent Service └───────────── id of the running workflow (BDA) ``` The two numbers are not values you choose or look up in a catalogue: they identify one specific agent inside one specific workflow execution. They change only when the workflow is edited or recreated: stopping and restarting the workflow without making changes does not change its ids. After an edit or a recreation, however, the configuration must be updated. Copy the URL from the *Workflow Designer* instead of writing it by hand, as described in [Get the agent URLs](#get-the-agent-urls). ## Before you begin Make sure you have: * An agent running inside a workflow. The endpoints exist only while the workflow is running: an agent whose workflow has been stopped or deleted answers with `404 – bda-id has not been initialized`. * Access to the *Workflow Designer* of that workflow, to copy the endpoint URL. * The API protocol exposed by the agent, `OpenCode` or `OpenAI`. * Access to the environment customization panel of the ALIDA instance, where the configuration is saved. ::: warning Instance-level configuration The agent configuration is not per-user: it is written in the environment file of the ALIDA instance and is therefore shared by every user of that instance. Point it to a workflow that is meant to stay running, because if that workflow is stopped the agent stops working for everyone. ::: ## Get the agent URLs ### Invocation URL (`url`) The agent is invoked through a REST endpoint exposed by the workflow, exactly like any other REST API port. Open the workflow in the *Workflow Designer*, select the agent, and copy the URL of the endpoint by clicking on it in the panel on the right side. ::: tip Output storage of the port Before the workflow is started, the port that exposes the endpoint must have an output storage of type `Remote` selected. Click on the dot representing the port on the agent, then choose an output storage of type `Remote` for it. If the output storage is not of this type, the workflow runs as a batch: it waits for the Service to terminate before moving on, but a long-running agent Service never terminates, so the workflow never reaches the point of exposing the endpoint. ::: ![service-exposing-endpoint](/images/service-exposing-endpoint.png) *Workflow Designer - panel exposing the endpoint URL* The copied URL has this form: ```text https://alida.devng.alidalab.it/events/bda/11150/11152 ``` For details on how ALIDA exposes and protects these endpoints, see [I/O Ports: REST API endpoints](../io-ports.md#rest-api-type). ::: tip OpenAI protocol For an agent exposing OpenAI-compatible APIs, such as the [ADK Agent](adk-agent.md), append `/v1` to the copied URL: ```text https://alida.devng.alidalab.it/events/bda/11150/11152/v1 ``` ::: ### Streaming URL (`streamingUrl`) The streaming endpoint has no copy button in the *Workflow Designer*: build it from the copied URL by inserting `streaming/` right after `/events/bda/` and keeping the rest of the path unchanged. ```text Copied URL: https://alida.devng.alidalab.it/events/bda/11150/11152 Streaming URL: https://alida.devng.alidalab.it/events/bda/streaming/11150/11152 ``` The `/v1` suffix used for OpenAI-compatible invocation is not added to the streaming URL. ## Write the configuration The configuration is a JSON object saved in the environment file of the instance, from the panel described in [Personalization of Environment Variables](../environment-customization.md). | Field | What to enter | | --- | --- | | `type` | `agent`, to declare the entry as an agent of the chat. | | `name` | Free text. It is the name shown to the user when choosing the agent in the chat. | | `url` | The invocation URL copied from the *Workflow Designer*, with the `/v1` suffix when the protocol is `OpenAI`. | | `streamingUrl` | The streaming URL derived from the copied URL, as described above. Leave it empty if the agent does not expose streaming. | | `token` | Leave empty (`""`): authentication of the logged-in user is handled by `extra.queryParams`. | | `protocol` | The protocol exposed by the agent: `OpenCode` for the [OpenCode Agent](opencode-agent.md), `OpenAI` for any agent with OpenAI-compatible APIs, such as the [ADK Agent](adk-agent.md). | | `contextPage` | The list of ALIDA pages where the agent is available in chat, as `{"path": ""}` entries, for example `/services` for the *Services* page. Leave the list empty to make the agent available on every ALIDA page. | | `extra.queryParams` | Additional request parameters. Keep `"token": "{{alida-token}}"`: the placeholder is replaced at runtime with the token of the logged-in user, which authenticates the call to the endpoint. | ::: warning The token placeholder is not an API key This token is different from the Ollama or MLflow API key. It is the authentication token issued by the ALIDA platform for the logged-in user, used to authorize the calls between internal components — here, from the chat to the agent endpoint. Do not replace the placeholder with a key of your own: leave it as {{alida-token}}. ::: ## Configuration examples In the examples below, replace the placeholders with the values of your running workflow: `` is the id of the running workflow (BDA), and `` is the id of the Service of the agent you started — you find it in the *Services* section of that workflow. Rather than assembling the URL by hand, open the workflow in the *Workflow Designer* and copy the URL of the endpoint by clicking on it, as described in [Get the agent URLs](#get-the-agent-urls): the copied URL already contains both ids. ### OpenCode ```json { "type": "agent", "name": "Custom Coding Agent", "url": "https:///events/bda//", "streamingUrl": "https:///events/bda/streaming//", "token": "", "protocol": "OpenCode", "contextPage": [ { "path": "/services" } ], "extra": { "queryParams": { "token": "{{alida-token}}" } } } ``` ### OpenAI-compatible endpoint Use this configuration for any agent that exposes OpenAI-compatible APIs. The ADK Agent is one agent that integrates this type of endpoint. ```json { "type": "agent", "name": "Alida Agent", "url": "https:///events/bda///v1", "streamingUrl": "https:///events/bda/streaming//", "token": "", "protocol": "OpenAI", "contextPage": [ { "path": "/services" } ], "extra": { "queryParams": { "token": "{{alida-token}}" } } } ``` The same configuration, filled in with the URLs copied from a running workflow, looks like this: ```json { "type": "agent", "name": "Alida Agent", "url": "https://alida.devng.alidalab.it/events/bda/11150/11152/v1", "streamingUrl": "https://alida.devng.alidalab.it/events/bda/streaming/11150/11152", "token": "", "protocol": "OpenAI", "contextPage": [ { "path": "/services" } ], "extra": { "queryParams": { "token": "{{alida-token}}" } } } ``` ## First request 1. Go to the page specified in `contextPage`, for example `/services`. 2. Open chat, select the agent by the `name` given in the configuration, and make a request appropriate to that context. 3. Verify the result before using or deploying the generated artifacts. ## Troubleshooting | Symptom | Cause and solution | | --- | --- | | `404 – bda-id has not been initialized` | The workflow that exposes the agent is not running, or the URL points to a workflow that no longer exists. Start the workflow and copy the URL again from the *Workflow Designer*. | | The agent is not listed in chat | The current page is not among those declared in `contextPage`. Reach one of the declared pages, or leave `contextPage` empty to make the agent available everywhere. | | The answer arrives all at once, or streaming fails | Check `streamingUrl`: `streaming/` must follow `/events/bda/`, and the URL must not end with `/v1`. | | The call is rejected as unauthorized | Check that `extra.queryParams.token` contains {{alida-token}} and that your user has the permissions to access the workflow that exposes the agent. |