Private preview: This feature is available in private preview and is off by default. Contact support to join the program to learn more.
BlueConic offers an Agent-to-Agent (A2A) server that follows the open A2A protocol. Your own agents, such as orchestration frameworks, internal copilots, and third-party AI agents, can discover BlueConic agents and send them tasks directly, without custom integration code.
Three agents are available:
Search agent: Finds BlueConic objects of a given type, such as segments, listeners, connections, plugins, or users, with an optional free-text filter. Results include only objects the application has permission to see, and counts are exact.
Growth Play Advisor agent: Recommends growth plays for a stated marketing goal, based on the data and current setup of your tenant. It doesn't change anything.
Design agent: Creates and updates segments from a plain-language description. It checks every rule against your tenant's stored data before it writes. It can't delete a segment.
Note: The Search and Growth Play Advisor agents are read-only. The Design agent changes data, segments only. Every result follows the application's scopes and the Run as user's permissions.
Before you begin
Availability: The Design agent, the authorization code flow for A2A, and tasks kept separate per user require release 105.0, which is rolling out now and reaches all customers by November 20, 2026.
Ask your BlueConic representative or support to turn on A2A for your tenant.
Make sure you have permission to create an application in Settings > Access management > Applications.
A2A works alongside the BlueConic MCP server. Your agents can call the MCP tools directly, hand tasks to the A2A agents, or both. See BlueConic Model Context Protocol (MCP).
Give an application access to A2A agents
Go to Settings > Access management > Applications.
Open an application, or select Add application.
Under OAuth 2.0 flow, select Client credentials flow or Authorization code flow. Use the authorization code flow when a signed-in user's tool calls the agents, such as the Claude Desktop plugin.
Under A2A agents, select the agents the application can call: Search agent, Growth Play Advisor agent, Design agent, or any combination.
For the Search agent, also grant the read scope for each object type it queries, such as Segments or Listeners.
Set a Run as user. A2A calls run as this user and follow that user's BlueConic permissions.
Turn the application ON, and select Save.
Copy the Client ID and Client secret for your agent's configuration.
Note: For the Design agent, the Run as user also needs permission to manage segments. BlueConic checks it before each write.
Tip: Use a separate OAuth application for the Design agent. You can then remove write access without touching the read-only agents.
Discover the agents
Each agent publishes an Agent Card that describes what it does. Point your agent at the catalog, or at a specific card:
Catalog of all agents:
https://tenantname.blueconic.net/.well-known/agent-card.json/catalog
Search agent:
https://tenantname.blueconic.net/.well-known/agent-card.json/search
Growth Play Advisor agent:
https://tenantname.blueconic.net/.well-known/agent-card.json/advisor
Design agent:
https://tenantname.blueconic.net/.well-known/agent-card.json/design
The default card, https://tenantname.blueconic.net/.well-known/agent-card.json, points to the Search agent.
Sign in
Request an access token with the client ID and client secret of your application:
curl -X POST "https://tenantname.blueconic.net/rest/v2/oauth/token" \
-d grant_type=client_credentials \
-d client_id="<client-id>" \
-d client_secret="<client-secret>"
The response contains an access_token and an expires_in value. Request a new token before the old one expires.
Send the token in the header of every A2A request:
Authorization: Bearer <access_token>
With the authorization code flow, your tool receives the token when the user signs in.
Send tasks to an agent
Send tasks to the A2A endpoint of each agent:
/rest/v2/a2a/search
/rest/v2/a2a/advisor
/rest/v2/a2a/design
Send requests with POST, using JSON-RPC. Use the SendMessage method to send a task, and GetTask to check on it.
Wait for the answer, stream progress, or check back later. A request that waits for the answer stops waiting after about 30 seconds and returns the task in its current state. BlueConic keeps task state for seven days, so your agent can resume a task that needs more input. Tasks are kept separate per application and per user.
Search agent
Send one JSON data part with these fields:
type(required): the object type. See the list below.prompt(optional): a natural-language filter, for exampleGDPR.limit(optional): the maximum number of objects to return.
Example data part:
{"type": "segment", "prompt": "GDPR", "limit": 5}To count the profiles in a segment, use profileCount and name the segment in prompt.
Supported values for type, exact and case-sensitive: segment, listener, connection, dialogue, plugin, user, role, channel, lifecycle, objective, contentstore, notebook, model, property, timeline_event_type, timeline_event_rollup, grouptype, tracker, and profileCount.
Note: Without a filter, the Search agent returns the same result every time. It uses a large language model (LLM) only to interpret a free-text filter, so filtered searches are best-effort.
Growth Play Advisor agent
Send one text part that describes your goal. Example requests:
What growth plays should I run for cart abandonment?
How can I improve conversion for new visitors?
Which segments should I target for a re-engagement campaign?
The Growth Play Advisor can take several minutes. Check on the task with GetTask until it's done. The answer is in the artifact named response.
Design agent
Send one text part that describes the segment, for example: "Create a segment of visitors from the US. Name it exactly 'US visitors'."
The Design agent finds the matching profile properties and checks every rule against your tenant's stored values before it writes.
When the segment is fully specified, it writes the segment at once. BlueConic doesn't ask anyone to confirm.
It handles one segment per request.
To change a segment, send a follow-up in the same conversation, with the contextId of the first task. An update replaces the segment's rules, tags, and base segments.
It never deletes a segment.
It can take longer than 30 seconds, so check on the task with
GetTask.
The completed task has two artifacts:
response: a text answer that describes what the agent did.
segment-write-result: the segment id, a filterSummary of the stored rules, and, for an update, the name.
Note: Use the segment-write-result data in your code. Don't parse the text answer.
Clarifying questions
The Design agent asks instead of guessing when a description is ambiguous, no property fits, a stored value fits only partly, or BlueConic refuses the write. The task state is then TASK_STATE_INPUT_REQUIRED, and the question is in status.message.
Answer with a new message that uses the same taskId and the same contextId, sent to the same agent. An answer sent to a different agent or with a new task ID is rejected.
Important: if the connection drops, call GetTask and read segment-write-result before you send the request again. Otherwise, a second segment can be created.
Who confirms the change?
BlueConic doesn’t ask a person to confirm a write by the Design agent. The write runs on the instruction of the calling agent, with the permissions of the Run as user.
Your agent must confirm with its own user before it asks the Design agent to create or change a segment.
Through MCP, the update tool is marked as destructive, so clients can ask for approval first. Not every client does this by default; ChatGPT doesn’t. Configure your client to ask before write actions.
Use a Run as user with only the permissions it needs.
Review the segments an agent creates or changes. The segment history shows “Design agent” as the source.
Test on a non-production tenant first.
Example requests
These calls work from any HTTP client. Replace tenantname with your tenant, and $TOKEN with your access token (see Sign in).
Call the Search agent
curl -X POST "https://tenantname.blueconic.net/rest/v2/a2a/search" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "SendMessage",
"params": {
"message": {
"role": "ROLE_USER",
"messageId": "7f1c2b9e-0000-4000-8000-000000000001",
"parts": [ { "data": { "type": "segment", "prompt": "GDPR", "limit": 5 } } ]
},
"configuration": { "returnImmediately": false }
}
}'
The response holds the task. The Search agent's answer is in the artifact named results:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"task": {
"id": "9195f21e-12a9-4fa8-960a-faaea085b7a7",
"status": { "state": "TASK_STATE_COMPLETED" },
"artifacts": [ {
"name": "results",
"parts": [ { "data": {
"type": "segment", "count": 1, "exact": true,
"interpretedAs": "name contains \"GDPR\"",
"objects": [ { "id": "374342b9-c614-4de5-91c1-52a3de0a5775", "name": "GDPR visitors" } ]
} } ]
} ]
}
}
}Check on a task
Send GetTask to the endpoint of the agent that owns the task:
curl -X POST "https://tenantname.blueconic.net/rest/v2/a2a/advisor" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -H "Accept: application/json" \
-d '{"jsonrpc":"2.0","id":2,"method":"GetTask","params":{"id":"<task-id>"}}'
Repeat the call every few seconds until status.state is TASK_STATE_COMPLETED, or TASK_STATE_INPUT_REQUIRED when the Design agent asks a question.
Create a segment with the Design agent
curl -X POST "https://tenantname.blueconic.net/rest/v2/a2a/design" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 3,
"method": "SendMessage",
"params": {
"message": {
"role": "ROLE_USER",
"messageId": "7f1c2b9e-0000-4000-8000-000000000002",
"parts": [ { "text": "Create a segment of visitors from the US. Name it US visitors." } ]
},
"configuration": { "returnImmediately": true }
}
}'
The response holds the task. Keep its id and contextId:
{
"jsonrpc": "2.0",
"id": 3,
"result": {
"task": {
"id": "<task-id>",
"contextId": "<context-id>",
"status": { "state": "TASK_STATE_WORKING" }
}
}
}
Read the result
Send GetTask to /rest/v2/a2a/design until the task is done. A completed task has two artifacts:
{
"jsonrpc": "2.0",
"id": 4,
"result": {
"id": "<task-id>",
"contextId": "<context-id>",
"status": { "state": "TASK_STATE_COMPLETED" },
"artifacts": [
{ "name": "response",
"parts": [ { "text": "<what the agent did>" } ] },
{ "name": "segment-write-result",
"parts": [ { "data": { "id": "<segment-id>", "filterSummary": "<rules as stored>" } } ] }
]
}
}
Use the data in segment-write-result in your code. Don’t parse the text in response.
Change the segment
Send a follow-up in the same conversation, with the contextId of the first task:
{ "role": "ROLE_USER", "contextId": "<context-id>", "messageId": "<new uuid>",
"parts": [ { "text": "Widen that to the last 90 days instead." } ] }
Answer a question
When status.state is TASK_STATE_INPUT_REQUIRED, read the question in status.message. Answer with the same taskId, sent to the same agent:
{ "role": "ROLE_USER", "taskId": "<task-id>", "contextId": "<context-id>", "messageId": "<new uuid>",
"parts": [ { "text": "<your answer>" } ] }Example apps
Note: Both example apps are attached at the end of this article. Scroll to the bottom to download a2a-python-client.zip and a2a-langgraph-example.zip.
1. Plain Python client: a2a-python-client.zip (recommended)
It needs only Python 3 and has no pip install. It calls the search, advisor and Design agents.
What you need first:
The
a2afeature flag is on for the tenant.An OAuth application with the client-credentials grant, and a run-as user who may manage segments.
The agents are switched on in the “A2A agents” section of the application settings.
Create a segment with the Design agent:
python3 a2a_client.py \
--base https://<your-tenant>.blueconic.net \
--client-id <client-id> \
--client-secret <client-secret> \
--design "create a segment of visitors from the US. Name it exactly 'US visitors'."
The task should end in TASK_STATE_COMPLETED. Then check Segments in BlueConic to see the new segment.
Other options:
Search agent:
--type segment(optional--prompt "..."and--limit 10)Advisor agent:
--advisor "Which growth plays fit a re-engagement goal?"Follow-up to the Design agent:
--context-id <id from the first reply> --design "widen that to the last 90 days instead"Self-signed test host: add
--insecure
The Design agent can take longer than 30 seconds. The client then polls every 2 seconds, for up to 2 minutes.
2. LangGraph example: a2a-langgraph-example.zip (optional)
This app shows how an agent framework can call BlueConic. It uses the official a2a-sdk. It calls the advisor agent only, not the Design agent. It needs Python 3.11 or later and AWS Bedrock access for two LLM steps.
cd a2a-langgraph-example
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env # fill in the values below
python -m app.main "We want to grow email opt-ins on the marketing site this quarter"
Values for .env: the tenant URL, the OAuth client ID and secret (the application needs the advisor agent switched on), the AWS credentials, AWS_REGION and BEDROCK_MODEL_ID. The README has the details.
Next steps
Decide which of your agents need the Search agent, the Growth Play Advisor agent, the Design agent, or the MCP tools, and grant only those.
Check the Run as user's permissions, because they limit what the Search agent returns.
FAQ, limits, and troubleshooting
Can A2A agents create or change objects?
Only the Design agent, and only segments. It can create and update segments. It can't delete them.
Can a signed-in user call an A2A agent?
Yes. A2A scopes work with authorization code applications as well as client credentials applications.
How current are profile counts?
Profile counts reflect the latest index update, not real time.
Are Agent Cards signed?
No. Agent Cards are served unsigned.
Does A2A support push notifications or other transports?
No. Check the task status instead of waiting for a push notification. The only transport is JSON-RPC.
Limitations
The Design agent writes without a confirmation step, and handles one segment per request.
The result includes a summary of the rules, but not a profile count. Open the segment in BlueConic to see the count.
Troubleshooting
The Design agent says you may not create or edit segments: the Run as user doesn’t have permission to manage segments.
A reply to a paused task is rejected: the reply went to a different agent, or used a new task ID.
