Introduction
As organizations explore AI capabilities, one of the challenge Pega Architects often face is understanding how to design and integrate external AI agents that can work with Pega AI Agents.
It is easy to create an AI agent inside Pega. But what happens when the capability you need already exists outside Pega. How do you expose that agent, make it available through an Agent-to-Agent (A2A) interface, connect it to Pega, and allow a Pega agent to delegate work to it?
In this article, we will build that integration from scratch. We will create a simple multi-agent solution consisting of:
- External A2A Agents – We will build two external agents in Python: a Credit Assessment Agent and a Fraud Assessment Agent. For this POC, the business logic is intentionally simple, but the same agent boundary could later encapsulate an ML model, LLM, enterprise service, or other business capability.
- Pega AI Agents – We will create two specialized Pega AI Agents that connect to the corresponding external Python agents and delegate the required work to them.
- Pega Orchestrator Agent – We will create an Orchestrator Agent that understands the user’s request and coordinates with one or both specialized Pega Agents to produce the final response.
Along the way, we will also see how to test the external agents independently, expose them using ngrok for development, configure the A2A connections in Pega, and bring the complete solution together.
By the end of the article, we will have a working multi-agent architecture in which Pega can delegate specialized tasks to external AI agents and coordinate their responses through an Orchestrator.
Scenario
Assume a loan application requires two independent assessments:
- Credit assessment
- Fraud assessment
Instead of implementing both capabilities inside Pega, we expose them as external A2A agents. Pega provides the orchestration layer, while the external agents own their respective business capabilities.
The Three Layers of the Solution
Before looking at the implementation, it helps to understand the three logical layers in the architecture.
Layer 1 — Pega Orchestration Layer
The Pega Orchestrator Agent is responsible for understanding the user’s request and determining which capabilities are required.
It is responsible for:
- Understanding the user’s intent
- Identifying the appropriate specialist capability
- Delegating the request to one or more specialist agents
- Combining results when multiple capabilities are required
- Presenting the final response to the user
Layer 2 — Pega Capability Layer
The Pega Specialist Agents represent specific business capabilities within the Pega ecosystem.
In this POC, we have:
- Credit Assessment Agent
- Fraud Assessment Agent
They provide the Pega-facing representation of the capability and delegate the actual processing to the corresponding external agent through A2A.
The important architectural point is that the Pega specialist agent does not need to know how the external capability is implemented. It only needs to know what capability is available and how to invoke it.
Layer 3 — External Agent Execution Layer
The external Python agents implement the actual capability outside Pega.
For this POC, the agents are implemented using Python and Flask and exposed through A2A endpoints.
The implementation behind these agents can evolve independently. The external agent could contain rule-based logic, invoke an ML model, call an enterprise service, access a database, use an LLM, or combine multiple sources.
From Pega’s perspective, these implementation details remain behind the A2A boundary.
Building the External Credit Score A2A Agent
At a high level, the Python agent needs to provide the following capabilities:
- A Flask-based HTTP service that can receive requests.
- An Agent Card available through the well-known Agent Card endpoint.
- An A2A endpoint capable of receiving the request from Pega.
- Logic to extract the applicant information from the incoming message.
- Credit assessment logic that produces a score, risk level, and recommendation.
- An A2A-compatible response containing the assessment result.
- A publicly reachable HTTPS endpoint so that Pega can communicate with the agent.
The implementation itself is relatively simple. The complexity remains in making sure that the external agent followed the expectations required for interoperability with Pega.
The Python business logic is trivial for the POC. The important part is ensuring that the external agent exposes the right contract, advertises itself correctly, accepts the expected A2A interaction and returns a response that the consuming Pega agent can interpret.
The Agent Card
One of the important pieces when building an external A2A agent is the Agent Card.
The Agent Card is exposed through the well-known endpoint:
GET /.well-known/agent.json
It provides the information a consuming system needs to understand the external agent, including its protocol version, capabilities, endpoint, and available skills.
For the agent to work correctly with Pega, I found that the Agent Card needs to include the relevant A2A metadata. In particular, the protocol version and the input and output modes of the skill are important.
A simplified version of the Agent Card used for the Credit Assessment Agent looks like this:
card = {
"protocolVersion": "0.2.5",
"capabilities": {
"streaming": False,
"pushNotifications": False
},
"description": "Provides credit assessment for loan applications",
"name": "Credit Assessment Agent",
"skills": [
{
"description": "Returns credit score and loan recommendation",
"id": "assess-credit",
"inputModes": [
"text/plain"
],
"name": "Assess Credit",
"outputModes": [
"text/plain"
],
"tags": []
}
],
"url": NGROK_URL,
"version": "1.0.0"
}
Note: The exact A2A metadata and protocol version should be aligned with the A2A implementation supported by the Pega version being used. The example in this article reflects the POC environment used for this implementation.
A useful troubleshooting lesson
When integrating an external A2A agent, don’t treat the Agent Card as simply a JSON endpoint that needs to return HTTP 200.
The card is part of the interoperability contract between the external agent and Pega. If the required metadata is missing or doesn’t accurately describe the agent’s capabilities, the integration may not work even though the endpoint itself is reachable and returns valid JSON.
Therefore, before troubleshooting the Pega configuration, I recommend independently validating:
- /.well-known/agent.json is publicly accessible.
- The Agent Card is valid JSON.
- The protocolVersion is specified correctly.
- Each skill has the appropriate inputModes and outputModes.
- The advertised url points to the correct public A2A endpoint.
- The skill description accurately represents the capability exposed by the agent.
This small validation step can save a lot of time because it separates Agent Card issues from Pega configuration, A2A request, and network issues.
GET vs POST — Both Have a Role
Another issue I encountered was around GET and POST requests.
At first glance, it is easy to assume that the external agent only needs to expose one HTTP endpoint. In practice, there are different interactions involved.
The Agent Card is retrieved using a GET request:
GET /.well-known/agent.json
The actual agent interaction requires a POST request to the A2A endpoint.
While debugging, the GET and POST request and response can be validated in ngrok inspector as shown below:
Sample Response structure code
Keep the Business Logic Independent
For our demonstration, the Credit Score Agent uses a simple implementation to generate: Credit Score, Risk Level and Recommendation. The actual logic is intentionally simple.
In a real implementation, the external agent could instead call:
- A credit bureau
- An internal scoring service
- A machine learning model
- A decision engine
- A database
- Multiple enterprise services
The important architectural point is that this implementation detail remains inside the external agent. Pega does not need to know how the credit score is calculated. From Pega’s perspective, it is simply communicating with an external agent that provides a credit assessment capability.
Building the Python Fraud Assessment Agent
The Fraud Assessment Agent follows the same A2A pattern as the Credit Assessment Agent. The implementation differs only in the business capability exposed by the agent. It has its own Agent Card, A2A endpoint and fraud-specific processing logic.
Test the Agent Before Connecting Pega
Before connecting the Python agent to Pega, I recommend testing the external agent independently.
External Agent Readiness Checklist:
- Flask application starts
- Agent Card is accessible
- Agent Card is valid JSON
- Advertised URL is correct
- A2A endpoint accepts POST
- Incoming A2A request is logged
- Business payload is extracted correctly
- Business logic executes successfully
- A2A response is returned
- Response can be validated independently
- Public HTTPS endpoint works through ngrok
If something fails after connecting the agent to Pega, we can then isolate whether the problem is with: Python Agent or A2A Contract or Network Connectivity or Pega Configuration
Expose the Python Agents Through ngrok
Why ngrok?
The Python A2A Agent is running locally on my machine. Pega, however, needs to reach that agent over the network.
ngrok provides a simple way to expose the local Flask application through a temporary public HTTPS endpoint. The ngrok URL becomes the endpoint that Pega can reach.
The flow becomes:
Pega → Public HTTPS URL → ngrok → localhost:5002 → Flask A2A Agent
This is particularly useful during development because you don’t need to deploy the Python agent to a cloud server just to test the Pega integration.
Step 1: Start the Python Agent
Start the Flask application first.
if the application is running on port 5003, we will see something like:
Starting Fraud Detection Agent…
* Running on http://127.0.0.1:5003
At this point, the agent is available locally but is not accessible from Pega.
Step 2: Start ngrok
Install ngrok and authenticate it with your ngrok account. (You can create a free account using your GitHub account or any email account)
Then create a tunnel to the port where your Flask application is running:
Script: ngrok http 5003
ngrok will provide a public HTTPS URL similar to:
Forwarding https:// → http://localhost:5003
Step 3: Use the ngrok URL in the Agent Card
The public URL generated by ngrok needs to be advertised by the external agent.
For example:
NGROK_URL = “https://”
And the Agent Card uses that URL:
“url”: NGROK_URL
Step 4: Verify the Agent Through the Public URL
Before configuring Pega, verify that the agent is accessible through ngrok.
First, open the Agent Card endpoint: https:///.well-known/agent.json
You should receive the Agent Card JSON.
Verify the A2A Endpoint
The most important test is to send an actual A2A request through the public ngrok URL.
At this point, verify three things:
- Agent Card is accessible
GET /.well-known/agent.json - The public URL reaches the Flask application
GET / - The A2A endpoint receives and processes the request
POST /
You should see the incoming request printed in the Flask console, followed by the A2A response. This gives the confidence that the complete external side is working before we start with Pega.
Create the Credit Score Agent in Pega
Now that the external agents are running and accessible, we can configure the corresponding agents in Pega.
- Create the Credit Assessment Agent and Connect Agent rule
- Configure its instructions
- Add the external A2A agent
- Configure the connection
Create the Fraud Assessment Agent in Pega
Repeat the same process for the Fraud Assessment Agent, as shown in the screenshots below:
Create the Pega Orchestrator Agent
Once all 3 agents and related rules are created, refer the agent in required channel.
I have configured the agent at both the levels: Application and CaseType.
All configurations are complete. Now let’s see it working.
Below example is for Application Level Agent Orchestrator:
Orchestrator Agent is requested to provide the Credit score, it invoked Credit Assessment Agent to get the score. Similarly for fraud assessment it invoked Fraud Assessment Agent and provide the response.
Below example is for Case level Agent Orchestrator:
Debug:
A few things that did not work the first time :
| What I expected | What actually happened | Lesson |
|---|---|---|
| HTTP 200 meant success | Pega could still fail to display the response | Validate the A2A response contract |
| Agent Card only needed to be reachable | Metadata affected interoperability | Treat Agent Card as a contract |
| GET endpoint was sufficient | Pega invoked the A2A endpoint using POST | Separate discovery from invocation |
| Python returned JSON | Pega still did not render the response | Response structure matters |
| Pega reported successful execution | The response was still empty in the UI | Separate execution success from response parsing |
Tools used for Debugging:
AI tracer:
In my Pega trial environment, AI tracer was opening only for Application Level Agents and not for Case Type level agents. Request and response data can be seen in the AI Tracer as shown in below screenshot
For Case Type Agent , I directly referred instance of Pega-Autopilot-Conversation to see the request and response, as shown in below screenshot.
I expect AI Tracer is also fetching the data from this instance.
NGROK Inspector
Any call made to you python agents hosted on ngrok can be inspected in ngrok inspector.
After completion of the Python Agents code, it can be tested directly from browser or terminal and those request & response will also be visible in inspector.
Also, any call from Pega to external Agent can be inspected here as well.
We can also ask the orchestrator to provide the details from both the agents as shown in below screenshot:
Key takeaways and next steps
We started with two independent Python agents and exposed them through A2A. We then connected those agents to specialized Pega agents and finally introduced a Pega Orchestrator capable of dynamically delegating requests to one or multiple specialist agents.
The agents can directly be configured in the flow as well and their response can be displayed to user on UI or used internally. For POC purpose, it looks better to see the agent response in agent window.
This implementation uses Flask and ngrok to demonstrate the A2A interaction. For a production implementation, the external agent would typically be hosted on an enterprise-managed platform rather than exposed through a temporary ngrok endpoint.
What this POC demonstrates
- Pega can discover an externally hosted agent through an Agent Card.
- Pega can invoke an external agent through A2A.
- The external agent can encapsulate its own business logic.
- Multiple external capabilities can be exposed as separate agents.
- Pega can use specialized agents behind an orchestrator.
- The external implementation can evolve independently from the Pega orchestration layer.
What this POC does not attempt to demonstrate
- Production-grade security
- Enterprise hosting of external agents
- Advanced LLM reasoning
- Production-scale observability
- Complex asynchronous agent workflows
- Enterprise authentication/authorization