Agent Architecture & A2A Protocol

Elementum agents operate at two levels: each agent has an internal architecture that balances AI reasoning with deterministic controls, and agents coordinate across organizational boundaries using the Agent-to-Agent (A2A) protocol. This page covers the internal component model, A2A discovery and authentication, the JSON-RPC messaging interface, streaming, and multi-turn conversations.

Individual Agent Architecture

Core Agent Components

Each Elementum agent follows a standardized internal architecture that balances AI capabilities with deterministic control structures:

Elementum Agent Architecture - Light Mode

Agent Component Functions

System Prompts: Define agent behavior, expertise domain, and operational constraints
Orchestrator: Manages execution flow, tool calls, and contextual state
LLM Engine: Provides natural language understanding and generation capabilities
Memory Systems: Maintain context, conversation history, and learned patterns
Tool Registry: Catalog of functions and integrations the agent can invoke
Customer Data Access: Secure, governed access to relevant business data

Deterministic Control Mechanisms

The agent orchestrator enforces deterministic behavior through:

Workflow Action Constraints: Predefined actions that limit agent behavior to approved operations
Data Access Controls: Strict boundaries around what data the agent can access and modify
Tool Invocation Rules: Defined conditions for when and how external tools can be used
Escalation Triggers: Automatic handoff to human oversight based on confidence thresholds or business rules

Multi-Agent Coordination via A2A Protocol

Agent2Agent (A2A) Protocol Implementation

The A2A protocol enables standardized communication between Elementum agents and external agent systems. The protocol operates through several key mechanisms:

For complete A2A protocol specification and additional resources, see the A2A Project Documentation.

Agent Discovery and Registration

Agent Card Structure

Each agent publishes a standardized Agent Card that serves as both a discovery mechanism and capability contract. The Agent Card includes:

Identity and Capabilities: Unique agent identifier and list of specific functions the agent can perform, such as document analysis, compliance checking, or data transformation.
Communication Endpoints: Technical connection details including A2A protocol endpoints and health check URLs for establishing secure communication channels.
Authentication Requirements: Security specifications covering authentication methods, required permissions, and access scopes needed for interaction.
Data Schemas: Structured definitions of expected input formats and guaranteed output formats to ensure compatible data exchange between agents.
Governance Metadata: Compliance and operational requirements including audit trails, data residency constraints, and regulatory certifications that govern agent interactions.

A2A Authentication

Elementum supports two authentication methods for A2A communication: OAuth Client Credentials Flow Standard OAuth 2.0 client credentials grant for machine-to-machine authentication. External agents obtain access tokens from an authorization server and include them in A2A requests. Self-Signed JWT Authentication For scenarios where external agents issue their own JWTs, Elementum validates tokens using the following configuration:

Field	Description
Header Name	The HTTP header containing the JWT token (typically `Authorization`)
Email Address Claim Name	The JWT claim containing the user identifier (e.g., `sub`, `email`). When configured, the agent runs with the permissions of the identified user.
JWKS URL	URL to the JSON Web Key Set endpoint for public key retrieval and token verification
PEM Key	Alternative to JWKS—paste the plaintext public key directly for JWT verification

Required Claims You can enforce additional JWT claims that must be present with specific values. This is useful for restricting access to particular clients or tenants:

Field	Description
Claim Name	The JWT claim to validate (e.g., `client_id`, `aud`, `tenant`)
Acceptable Values	Comma-separated list of values that satisfy the claim requirement

Use required claims to scope A2A access—for example, require client_id to match your partner’s registered client identifier, or validate aud contains your agent’s expected audience.

A2A Communication Flow

Inter-Agent Communication Patterns

Synchronous Request-Response

Direct agent-to-agent calls for immediate responses
Timeout handling and circuit breaker patterns
Used for validation, lookup, and simple transformations

Asynchronous Task Delegation

Long-running operations with callback notifications
Status polling and progress updates
Used for analysis, document processing, and complex workflows

Event-Driven Coordination

Agents subscribe to relevant business events
Reactive processing based on data changes
Used for monitoring, alerting, and automated responses

Workflow Integration Architecture

Deterministic Structure Around Non-Deterministic Agents

Agents operate within workflow frameworks that provide governance and predictability:

Workflow-Agent Integration Points

Task Assignment: Workflow engine determines when and where to invoke agents
Context Provision: Agents receive structured context and constraints from workflow state
Result Validation: Agent outputs are validated against business rules before proceeding
Exception Handling: Failed or low-confidence agent responses trigger defined escalation paths

Connecting to an Elementum Agent via A2A

External systems can connect to Elementum agents that have been configured for A2A access. The connection follows the standard A2A handshake pattern. Elementum implements A2A protocol version 0.3.0 with streaming support.

The A2A protocol is an evolving standard. The examples in this documentation reflect Elementum’s current implementation. Contact your Elementum representative if you have questions about integration.

Discover Agent Capabilities

Each Elementum agent has a unique A2A endpoint URL in the format:

https://agent-{agentId}-{orgDomain}.elementum.io/a2a/v1

Retrieve the Agent Card to understand the agent’s capabilities, supported input/output modes, and available skills:

GET https://agent-{agentId}-{orgDomain}.elementum.io/a2a/v1/.well-known/agent.json

The Agent Card response includes:

Agent name and description
Supported protocol versions
Available skills and their descriptions
Authentication requirements
Capability flags (streaming, push notifications)

Send a Message to Initiate a Task

Use the message/send method to start an interaction:

{
  "jsonrpc": "2.0",
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "Create a support ticket for login issues"
        }
      ]
    }
  },
  "id": 1
}

Sending Attachments Messages can include file attachments alongside text content. To send an attachment, add a file part to the parts array with the file’s name, contentType, and a uri pointing to the file location:

{
  "jsonrpc": "2.0",
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "Help me with my orders"
        },
        {
          "kind": "file",
          "name": "orders.csv",
          "contentType": "text/csv",
          "uri": "https://example.com/files/orders.csv"
        }
      ]
    }
  },
  "id": 1
}

Each file part requires the following fields:

Field	Description
`kind`	Must be `"file"` to indicate an attachment
`name`	The filename including extension (e.g., `"orders.csv"`)
`contentType`	The MIME type of the file (e.g., `"text/csv"`, `"application/pdf"`, `"image/png"`)
`uri`	A URL where the file can be retrieved. The file must be accessible at this URI at the time the message is processed.

You can include multiple file parts in a single message, and they can be combined with text parts in any order. Both message/send and message/stream support attachments.

The file referenced by uri must be publicly accessible or reachable by the Elementum platform at the time the agent processes the message. If the file cannot be retrieved, the agent may not be able to process the attachment.

Receive Task Response

The agent returns a JSON-RPC response containing a Task object. The response includes a contextId that you can use for follow-up messages:

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "id": "8f1dfa7f-76c3-4368-8799-3116df7f7992",
    "contextId": "7584685c-e711-4e91-8d8e-e11484bff7b5",
    "status": {
      "state": "completed"
    },
    "history": [
      {
        "role": "user",
        "parts": [{"kind": "text", "text": "Create a support ticket for login issues"}],
        "taskId": "8f1dfa7f-76c3-4368-8799-3116df7f7992",
        "contextId": "7584685c-e711-4e91-8d8e-e11484bff7b5"
      }
    ],
    "artifacts": [
      {
        "artifactId": "6299dcdc-0774-41a7-b35c-0018b1fbbba3",
        "parts": [{"kind": "text", "text": "Support ticket #12345 created successfully."}]
      }
    ],
    "kind": "task"
  }
}

Streaming Responses

Elementum agents support streaming responses via message/stream using Server-Sent Events (SSE). This delivers real-time updates as tasks are processed — useful for long-running operations or when you want to display incremental progress to users. Initiating a Streaming Request Use the message/stream method instead of message/send:

{
  "jsonrpc": "2.0",
  "method": "message/stream",
  "params": {
    "message": {
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "Analyze the quarterly sales data"
        }
      ]
    }
  },
  "id": 1
}

Event Types

Every streaming response contains two event kinds, per the A2A spec:

Kind	Purpose
`status-update`	Agent lifecycle and tool execution notifications
`artifact-update`	The agent’s response content, streamed incrementally

TaskStatusUpdateEvent

Status updates track what the agent is doing. The status.state field progresses through submitted → working → completed. A status-update with state: "working" and no message means the agent is processing but has not called a tool yet. When the agent executes a tool, it emits an additional status-update with state: "working" and a status.message containing a description of the tool being executed:

{
  "taskId": "97fa3b19-...",
  "contextId": "4638cf82-...",
  "status": {
    "state": "working",
    "message": {
      "role": "agent",
      "parts": [
        { "kind": "text", "text": "Executing tool: Creating item..." }
      ]
    }
  },
  "kind": "status-update",
  "final": false
}

If the agent calls multiple tools during a single request, each tool execution produces its own status-update event in sequence. The final event in every stream is a status-update with state: "completed" and final: true.

TaskArtifactUpdateEvent

Artifact updates carry the agent’s text response, streamed token-by-token. Each event includes append: true and contains one text chunk. The last chunk in the sequence has lastChunk: true.

{
  "taskId": "97fa3b19-...",
  "contextId": "4638cf82-...",
  "artifact": {
    "artifactId": "12c26a10-...",
    "parts": [
      { "kind": "text", "text": "Here" }
    ]
  },
  "append": true,
  "lastChunk": false,
  "kind": "artifact-update"
}

Event Sequences

The order of events in a stream depends on whether the agent calls any tools while processing the request.

No tool calls
Single tool call
Multiple tool calls

The simplest case — the agent responds directly without executing any tools:

status-update   → state: submitted
status-update   → state: working
artifact-update → first token           (append: true)
...
artifact-update → last token            (append: true, lastChunk: true)
status-update   → state: completed      (final: true)

The agent calls one tool before generating a response. The tool execution appears as an additional working status with a message:

status-update   → state: submitted
status-update   → state: working
status-update   → state: working, message: "Executing tool: Creating item..."
artifact-update → first token           (append: true)
...
artifact-update → last token            (append: true, lastChunk: true)
status-update   → state: completed      (final: true)

The agent calls several tools in sequence. Each tool execution produces its own status-update event:

status-update   → state: submitted
status-update   → state: working
status-update   → state: working, message: "Executing tool: Searching available skills..."
status-update   → state: working, message: "Executing tool: Loading skill..."
status-update   → state: working, message: "Executing tool: Creating record..."
artifact-update → first token           (append: true)
...
artifact-update → last token            (append: true, lastChunk: true)
status-update   → state: completed      (final: true)

Key Fields

Field	Description
`taskId`	Unique identifier for the task
`contextId`	Context identifier for multi-turn conversations
`kind`	Event type: `status-update` or `artifact-update`
`final`	`true` when the stream is complete
`append`	`true` indicates content should be appended to previous chunks
`lastChunk`	`true` when this is the final chunk of an artifact

Stream Handling Requirements

Events are delivered in order and must not be reordered
The stream ends when you receive a status-update event with "final": true
Terminal states include: completed, failed, canceled, rejected
Capture the contextId from the response for follow-up messages in multi-turn conversations

Task States

A2A tasks progress through defined lifecycle states:

State	Description
`submitted`	Task has been created and acknowledged
`working`	Task is actively being processed
`input-required`	Agent needs additional information to proceed
`completed`	Task finished successfully (terminal)
`failed`	Task encountered an error (terminal)
`canceled`	Task was canceled before completion (terminal)
`rejected`	Agent declined to perform the task (terminal)

Multi-Turn Conversations

The A2A protocol supports multi-turn conversations through the contextId field. When you send an initial message, the server generates a contextId in the response. Include this contextId in subsequent messages to continue the conversation. Initial Request:

{
  "jsonrpc": "2.0",
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "Hi, I need help with a support ticket"
        }
      ]
    }
  },
  "id": 1
}

Follow-up Request (using contextId from response):

{
  "jsonrpc": "2.0",
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "The issue is with login authentication"
        }
      ],
      "contextId": "a269e867-fe40-4588-a381-c2596aeb3557"
    }
  },
  "id": 2
}

The contextId groups related messages, enabling the agent to maintain conversational continuity across multiple interactions. When an agent requires additional input, it returns a task with input-required status—use the same contextId to provide the requested information.

Testing A2A Connections

To test your A2A integration with Elementum agents, use the official A2A Inspector tool: A2A Inspector: github.com/a2aproject/a2a-inspector The inspector allows you to:

Fetch and validate Agent Cards
Send test messages and view responses
Monitor streaming events in real-time
Debug authentication and protocol issues

Protocol Version

Elementum currently implements A2A protocol version 0.3.0 with streaming support. The examples in this documentation reflect the current implementation. For the complete A2A protocol specification, see a2a-protocol.org.

Next Steps

Building Agents — Create an agent, configure tools, and add it to your app
Agent tools, deployment, and integrations — Tool types, deployment channels, and external agents via App Intelligence
Help & Resources — Support and additional documentation

Overview

Capabilities

Agent Management

Agent Integrations

Individual Agent Architecture

Core Agent Components

Agent Component Functions

Deterministic Control Mechanisms

Multi-Agent Coordination via A2A Protocol

Agent2Agent (A2A) Protocol Implementation

Agent Discovery and Registration

Agent Card Structure

A2A Authentication

A2A Communication Flow

Inter-Agent Communication Patterns

Workflow Integration Architecture

Deterministic Structure Around Non-Deterministic Agents

Workflow-Agent Integration Points

Connecting to an Elementum Agent via A2A

Discover Agent Capabilities

Send a Message to Initiate a Task

Receive Task Response

Streaming Responses

Event Types

TaskStatusUpdateEvent

TaskArtifactUpdateEvent

Event Sequences

Key Fields

Stream Handling Requirements

Task States

Multi-Turn Conversations

Testing A2A Connections

Protocol Version

Next Steps

Overview

Capabilities

Agent Management

Agent Integrations

​Individual Agent Architecture

​Core Agent Components

​Agent Component Functions

​Deterministic Control Mechanisms

​Multi-Agent Coordination via A2A Protocol

​Agent2Agent (A2A) Protocol Implementation

​Agent Discovery and Registration

​Agent Card Structure

​A2A Authentication

​A2A Communication Flow

​Inter-Agent Communication Patterns

​Workflow Integration Architecture

​Deterministic Structure Around Non-Deterministic Agents

​Workflow-Agent Integration Points

​Connecting to an Elementum Agent via A2A

​Discover Agent Capabilities

​Send a Message to Initiate a Task

​Receive Task Response

​Streaming Responses

​Event Types

​TaskStatusUpdateEvent

​TaskArtifactUpdateEvent

​Event Sequences

​Key Fields

​Stream Handling Requirements

​Task States

​Multi-Turn Conversations

​Testing A2A Connections

​Protocol Version

​Next Steps

Individual Agent Architecture

Core Agent Components

Agent Component Functions

Deterministic Control Mechanisms

Multi-Agent Coordination via A2A Protocol

Agent2Agent (A2A) Protocol Implementation

Agent Discovery and Registration

Agent Card Structure

A2A Authentication

A2A Communication Flow

Inter-Agent Communication Patterns

Workflow Integration Architecture

Deterministic Structure Around Non-Deterministic Agents

Workflow-Agent Integration Points

Connecting to an Elementum Agent via A2A

Discover Agent Capabilities

Send a Message to Initiate a Task

Receive Task Response

Streaming Responses

Event Types

TaskStatusUpdateEvent

TaskArtifactUpdateEvent

Event Sequences

Key Fields

Stream Handling Requirements

Task States

Multi-Turn Conversations

Testing A2A Connections

Protocol Version

Next Steps