Agent Architecture & A2A Protocol - Elementum Documentation

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.

Direction of A2A Communication

Elementum agents act as A2A receivers (servers), not A2A clients. External systems — other AI agents, automation platforms, or custom applications — connect to an Elementum agent: they retrieve its Agent Card, authenticate, and send it messages. See Connecting to an Elementum Agent via A2A for the receiver-side setup. Elementum does not act as an A2A client. There is no way to install, import, or register an external agent’s Agent Card in Elementum, and an Elementum agent cannot call out to another system’s A2A endpoint to discover or consume its capabilities. To use an external, third-party agent’s capabilities inside an Elementum workflow, connect a managed agent through App Intelligence rather than A2A. Elementum supports two managed agent runtimes:

Snowflake Cortex Agents — agents that run on your Snowflake data warehouse.
AWS Bedrock Agents — agents built in your own AWS account.

Managed agents are configured per App and invoked from automations using Run Agent Task.

A2A direction	Supported?	How
External system → Elementum agent	Yes	Enable A2A on the agent, then the caller retrieves the Agent Card and sends messages. See Connecting to an Elementum Agent via A2A.
Elementum agent → external A2A agent (install or consume an external Agent Card)	No	Not supported over A2A. Use App Intelligence with a Snowflake Cortex or AWS Bedrock managed agent instead.

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.

A2A is one-directional in Elementum: your agent is the receiver, and the external system is the caller. An Elementum agent cannot consume or install another system’s Agent Card. To bring an external agent’s capabilities into a workflow, connect a managed agent through App Intelligence (Snowflake Cortex or AWS Bedrock). See Direction of A2A Communication.

To turn on A2A capabilities for your agent, select the agent and click the Connections tab. Toggle on A2A Streaming to enable A2A protocol communication. For additional conversation settings such as automatic record creation and inactivity timeouts, see A2A Conversation Settings. 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.

Configure A2A Authentication

Configure how external systems authenticate when calling your agent from the Authentication section of the agent’s Configure page. Elementum supports two authentication methods:

OAuth — Standard OAuth 2.0 client credentials grant for machine-to-machine access. No additional fields are required in the Agent Configuration page.
JWT — Self-signed JSON Web Tokens issued by an external system and validated by Elementum. Requires the configuration below.

The Authentication section controls how callers prove their identity to the agent. Streaming behavior is configured separately on the Connections tab; see A2A Conversation Settings.

JWT Authentication

Click + Add Authentication in the JWT section to open the configuration dialog. Elementum validates incoming tokens against a public key you provide.

Field	Description
Header Name	The HTTP header that carries the JWT token on incoming requests. Defaults to `Authorization`.
Email Address Claim Name	The JWT claim that contains the caller’s email address (commonly `sub` or `email`). Elementum extracts this value from the validated token and runs the agent as that user, applying that user’s permissions.
JWKS URL / Plain Text	Toggle between providing a JWKS endpoint or pasting a public key directly. Choose JWKS URL when your identity provider exposes a JSON Web Key Set endpoint, or Plain Text to paste a PEM-formatted public key.
Required Claims	Optional. Click + Add Claim to require specific claims with specific values in the token — for example, restricting access by `client_id`, `aud`, or `tenant`. Tokens missing the claim or carrying an unaccepted value are rejected.

The caller signs each request with their private key, and Elementum verifies the signature using the configured public key. Because only the private key holder can produce a valid signature, a successful verification confirms the request’s authenticity.

If JWT-authenticated requests appear to run as the agent’s publisher instead of the calling user, check the following:

JWT authentication is enabled in the Authentication section.
The Email Address Claim Name matches the claim actually present in the token.
The configured JWKS URL is reachable, or the pasted public key is current and correctly formatted.

For the protocol-level specification—including required claim semantics and authentication flow details—see A2A Authentication below.

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.

A2A Conversation Settings

Configure conversation behavior for A2A agents on the Connections tab of the agent detail page.

A2A Streaming

Enable streaming responses for A2A protocol communication with the agent. When turned on, external systems can use the message/stream method to receive real-time, incremental responses. See Streaming Responses for protocol details.

Create a Record

When enabled, Elementum automatically creates a record when a conversation is initiated via the A2A protocol. This requires a conversation inactivity timeout to be configured.

Conversation Inactivity Timeout

Set the duration of inactivity (in minutes) before a conversation is automatically closed. When a conversation times out or completes, it can trigger follow-up automations.

Enable Create a Record and set a Conversation Inactivity Timeout to use the Agent Conversation Ended trigger in an App’s automation. This lets you run follow-up workflows — such as summarizing transcripts, updating CRM records, or generating reports — after an A2A conversation wraps up.

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

​Individual Agent Architecture

​Core Agent Components

​Agent Component Functions

​Deterministic Control Mechanisms

​Multi-Agent Coordination via A2A Protocol

​Agent2Agent (A2A) Protocol Implementation

​Direction of A2A Communication

​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

​Configure A2A Authentication

​JWT Authentication

​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

​A2A Conversation Settings

​A2A Streaming

​Create a Record

​Conversation Inactivity Timeout

​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

Direction of A2A Communication

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

Configure A2A Authentication

JWT Authentication

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

A2A Conversation Settings

A2A Streaming

Create a Record

Conversation Inactivity Timeout

Testing A2A Connections

Protocol Version

Next Steps