Skip to content

FEAT: Add A2ATarget for Agent-to-Agent protocol communication - #2771

Merged
Richard Lundeen (richlundeen) merged 7 commits into
microsoft:mainfrom
radeksixi:feat/a2a-prompt-target
Sep 30, 2026
Merged

Richard Lundeen (richlundeen) merged 7 commits into
microsoft:mainfrom
radeksixi:feat/a2a-prompt-target

Conversation

@radeksixi

@radeksixi Radek (Sixi) (radeksixi) commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor

Closes #2824

Summary

Adds A2ATarget so PyRIT can test agents exposed through the Agent-to-Agent (A2A) protocol, including Microsoft Foundry incoming A2A endpoints.

Implementation

  • Uses the official a2a-sdk through the optional pyrit[a2a] extra and the all extra. The SDK handles JSON-RPC serialization and protocol compatibility. The dependency is bounded to >=1.1.5,<2 and included in uv.lock.
  • Supports A2A 0.3 (default), 1.0, and agent-card discovery with protocol_version="auto". Supports custom card paths. Discovery errors propagate without a silent protocol fallback.
  • Maps each PyRIT conversation to an upstream context. Input-required and authentication-required tasks continue with their task ID; completed tasks are not reused. Sends and resets are serialized per conversation, while different conversations can run concurrently.
  • Declares text-only, multi-turn support without native system prompts, editable history, or other unsupported capabilities. Rejects single-turn overrides because the upstream agent retains history. Requires an actual upstream context ID when local history exists. Prompt normalization remains a framework responsibility.
  • Accepts static bearer tokens, async token providers, configurable API-key headers, or custom HTTPX authentication. Token providers run before discovery, submission, retries, and polls. Conflicting authentication options are rejected.
  • Separates HTTPX per-phase timeouts from the polling deadline. Supports explicit timeout=None, validates timeout and polling values, and rejects conflicting timeout settings. Polling HTTP 429 honors Retry-After or uses exponential backoff within the polling deadline. The configured request-rate limit covers submission attempts and polls, excluding discovery.
  • Retries submission only after an explicit HTTP 429, retaining the same message ID. Parsing and polling are outside submission retries. Empty accepted results and relayed model errors do not cause automatic resubmission. A polling timeout does not cancel the remote task.
  • Returns PyRIT error responses for failed, canceled, or rejected tasks. Input-required questions take priority over partial artifacts.
  • Uses typed SDK objects, the shared HTTPX client factory, and separate submission, polling, response, and error helpers. Identifiers include the endpoint, protocol, card path, and optional non-secret routing label, but not credentials or timeouts.

Integration coverage

The local integration tests use the official SDK server over loopback HTTP rather than a hand-written protocol server. They cover 0.3 and 1.0, discovery, persisted history, continuation, failures, and prevention of duplicate submissions after polling or empty results. sse-starlette is an explicit development dependency required by the SDK server.

Integration tests require RUN_ALL_TESTS=true. The separate Foundry test also requires A2A_FOUNDRY_ENDPOINT, uses a static token or a refreshable Entra token provider with the https://ai.azure.com/.default scope, and requires a successful text response. It does not create Azure resources.

Target documentation covers installation, authentication, identity, lifecycle, limitations, timeout behavior, and integration-test setup.

Validation

For commit 7e12ce329:

  • 100 focused unit and local SDK integration tests passed.
  • All pre-commit hooks passed, including full production type checking.
  • Missing optional SDK behavior passed: 1 test passed and 83 SDK-dependent tests skipped.
  • Integration gating passed: all 17 integration cases skipped when RUN_ALL_TESTS=false.
  • The dependency lock consistency check passed.

The live Foundry test was not run because no endpoint was configured. No Azure resources were created. The author's earlier Foundry results applied to the pre-SDK implementation and do not verify the current SDK adapter.

Introduces A2ATarget, enabling PyRIT to red-team multi-agent systems and services communicating over the Agent-to-Agent (A2A) protocol.

Key features:
- Dual-spec protocol negotiation: supports A2A v0.3 (message/send) with automatic fallback to v0.2 (tasks/send) on JSON-RPC -32601.
- Multi-turn conversation task continuity: tracks and preserves active server task IDs per conversation session.
- Robust response and refusal handling: captures JSON-RPC error refusals as conversational evidence rather than raising unhandled exceptions.
- Agent card discovery: provides get_agent_card_async() to inspect declared agent capabilities at standard discovery paths.
- Auth support: handles Bearer token and custom API-Key headers.
- Comprehensive unit test suite covering v0.3, v0.2 fallback, task continuity, refusals, and agent card discovery.
@radeksixi

Copy link
Copy Markdown
Contributor Author

@microsoft-github-policy-service agree

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for adding this! We are interested in including A2A support in PyRIT. The overall direction looks good, and the target follows the main PyRIT target contract.

The main change I would like before merging is to use the official A2A Python SDK (a2a-sdk), rather than maintain our own protocol implementation. It is published on PyPI and supports A2A v1.0 with v0.3 compatibility. Using its typed messages, agent-card discovery, and client transport would reduce the version-specific code we need to maintain. A2ATarget can remain a thin adapter that owns PyRIT message mapping, identifiers/capabilities, upstream context tracking, and error mapping. An optional a2a extra would fit our existing dependency pattern.

A few gaps to address during that change:

  • Safe polling retries: A 429 from tasks/get currently retries the whole send method, which submits the prompt again with a new message ID. Retry the poll against the existing task instead of creating duplicate agent work.
  • Task result handling: Failed or canceled tasks currently become ordinary text responses with no error flag. An input-required task with partial artifacts can also return those artifacts instead of the question in its status message. Handle these states explicitly, and do not use str(result) as an agent answer when there is no supported text.
  • Timeouts: The blocking send uses HTTPX's five-second default timeout. The 120-second task timeout only starts after that response arrives, so it does not protect a slow initial request.
  • Protocol versions: The v02 branch does not match the published v0.2.5 format, which already uses message/send and kind. The 0.3+ claim also needs narrowing because v1.0 has breaking changes. This is a strong reason to let the SDK handle protocol compatibility.
  • Identity and capability limits: Include non-secret protocol/routing settings that affect behavior in the target identifier. If stored history exists but the upstream context is missing, fail explicitly or provide a supported restoration path instead of continuing with only the latest message. Capability overrides should not advertise features the adapter cannot send.
  • Integration coverage: We should have a real HTTP integration test against a deterministic SDK-based agent, not only mocked responses. Cover multi-turn context, input-required continuation, failed tasks, and a polling 429 that does not resubmit the prompt. An environment-gated test against an owned Foundry agent would also be useful for real authentication and service interoperability.

Requesting changes mainly for the SDK direction and integration coverage. This is a useful addition, and I would like to get it into PyRIT with the protocol details handled by the maintained SDK.

@radeksixi

Copy link
Copy Markdown
Contributor Author

Thanks for the thorough and constructive review Richard Lundeen (@richlundeen)! I completely agree with the direction. Adopting the official a2a-sdk as an optional dependency (pyrit[a2a]) is a much cleaner architecture for PyRIT long-term than maintaining raw protocol serialization and dialect fallbacks.

I will update the PR with the following changes:

  1. a2a-sdk integration:

    • Add a2a optional extra to pyproject.toml (and sync into all).
    • Refactor A2ATarget to use a2a-sdk's typed models, client, and agent card discovery, keeping A2ATarget focused on PyRIT message adaptation, capability limits, and session/context mapping.
    • Follow the standard lazy-import pattern with a descriptive ImportError (pip install pyrit[a2a]).
  2. Safe polling & retry handling:

    • Scope 429 retries during tasks/get polling to the polling loop itself, ensuring a polling rate limit does not re-trigger _send_prompt_to_target_async or resubmit the prompt with a new message ID.
  3. Explicit task lifecycle states:

    • Properly map failed and canceled task states to response_type="error".
    • For input-required, prioritize the question from status.message over partial artifacts, and eliminate fallback to raw str(result).
  4. Timeouts:

    • Configure HTTP client / request timeouts to respect task_timeout_seconds (or an explicit request timeout) so blocking sends are properly protected against slow initial responses.
  5. Target identity & context validation:

    • Include relevant non-secret routing/protocol settings in the target identifier.
    • Explicitly fail if multi-turn history exists but upstream context is missing, rather than silently dropping prior turns. Ensure capability declarations match adapter capabilities.
  6. Integration tests:

    • Add deterministic HTTP integration test coverage against a local SDK-based agent server covering multi-turn context continuity, input-required continuation, task failure states, and polling 429 without prompt resubmission.
    • Add an environment-gated integration test for Microsoft Foundry A2A endpoints (@pytest.mark.skipif(...)).

I'll push the updates shortly. Thanks again!

@radeksixi

Copy link
Copy Markdown
Contributor Author

Also for additional context on motivation and broader ecosystem integration: I built agent-redteam-benchmark and actively develop agent-probe, using them to evaluate agent targets across diverse scenarios. I am also preparing a second red-teaming agent with more advanced orchestration strategies that will build upon this A2A target integration.

@radeksixi

Copy link
Copy Markdown
Contributor Author

The updates are pushed in commit 0f76903:

  • Official a2a-sdk adoption: Added a2a optional dependency (a2a-sdk>=1.1.0) to pyproject.toml (synced into all), with lazy import error messaging (pip install pyrit[a2a]). Replaced raw JSON-RPC dialect implementation with a2a-sdk client transport and typed models.
  • Safe polling retries: Scoped 429 handling during task polling to retry get_task against the existing task ID without restarting _send_prompt_to_target_async or resubmitting the prompt.
  • Task lifecycle handling: Mapped failed, canceled, and rejected task states to response_type="error". For input-required tasks, the agent question is extracted from status.message (preventing partial artifacts from overwriting the question) without raw str(result) fallbacks.
  • Timeouts: Configured httpx.Timeout using request_timeout_seconds (defaulting to task_timeout_seconds), protecting initial blocking sends from default HTTPX timeouts.
  • Identity & capability limits: Added non-secret configuration (endpoint, protocol_version, task_timeout_seconds) to ComponentIdentifier. Explicitly raise ValueError if multi-turn history exists without an upstream context ID (with set_conversation_context available for manual restoration). Validated custom configuration capabilities to reject modalities other than text or system prompts.
  • Testing:
    • 20 unit tests covering typed message results, task completion, input-required questions and continuation, failed/canceled error mappings, content filter handling, polling 429 without resubmission, timeout handling, and capability validation.
    • 4 real HTTP integration tests against a local deterministic A2A server (multi-turn memory recall, input-required flow, failed task, polling 429 with verified single prompt submission) + environment-gated test for Microsoft Foundry.
    • Full prompt target unit suite: 1364 passed, 31 skipped; ruff check, ruff format, and ty check clean.

Use refreshable HTTP authentication, serialize conversation state, validate capabilities and timeouts, and bound task polling retries. Add official SDK integration coverage and lock optional dependencies.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@richlundeen
Richard Lundeen (richlundeen) added this pull request to the merge queue Sep 30, 2026
Merged via the queue into microsoft:main with commit 9cbeb4a Sep 30, 2026
49 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

FEAT: A2ATarget for Agent-to-Agent (A2A) protocol endpoints

2 participants