Serve an agent through A2A

Add an A2A interface to the root agent-card.yaml. Harnest mounts only the bindings declared by the compiled card; you do not implement A2A route handlers.

agent-card.yaml

name: Support agent
description: Answers product questions and triages support requests.
version: 1.0.0
supportedInterfaces:
  - url: https://agents.example.com/support/a2a
    protocolBinding: HTTP+JSON
    protocolVersion: "1.0"
capabilities:
  streaming: true
  pushNotifications: false
defaultInputModes:
  - text/plain
defaultOutputModes:
  - text/plain
  - application/json
skills:
  - id: answer-product-question
    name: Answer product questions
    description: Finds and explains product information.
    tags: [support, product]

The URL path, /support/a2a in this example, becomes the mounted route. Use the public deployment URL in the Agent Card, then serve from the agent folder:

harnest serve .

Discover the card at GET /.well-known/agent-card.json. Use A2A 1.0 with HTTP+JSON or JSONRPC; version 0.3 remains supported on both. Test the HTTP+JSON binding at the exact path declared by the card:

curl -sS -X POST http://127.0.0.1:1907/support/a2a/message:send \
  -H 'A2A-Version: 1.0' \
  -H 'Content-Type: application/a2a+json' \
  --data '{"message":{"messageId":"demo-1","role":"ROLE_USER","parts":[{"text":"Hello"}]},"configuration":{"historyLength":0}}'

Understand when a Task exists

Interaction	A2A result
Blocking request that finishes directly	`Message`
Streaming request	Tracked `Task` and updates
`returnImmediately` request	Tracked `Task`
Human approval or client-tool wait	`Task` with input required
Durable external or queued wait	Persisted `Task` when the checkpointer supports it

Harnest supplies GetTask, filtered ListTasks, CancelTask, and explicit Task subscriptions. These operations are part of the mounted adapter, but callers use them only when their workflow needs Task state.

Persist A2A Tasks

Checkpoint authority	A2A Task behavior
`MemoryStore`	Task snapshots survive within one process only
`PostgresStore` or `RedisStore`	Lookup, artifacts, subscriptions, and terminal state survive restarts and replicas
Native `LangGraphStore` or `ADKStore`	A2A snapshots remain process-local because the native wrapper does not implement Harnest A2A persistence

Register a built-in Harnest store for both session and checkpoint responsibilities when A2A Tasks must survive a restart:

Create lib/state.py

lib/state.py

import os

from harnest.store import PostgresStore

state = PostgresStore(os.environ["DATABASE_URL"])

Create lifecycle/storage.py

lifecycle/storage.py

from harnest import lifecycle
from harnest.lib.state import state

@lifecycle.storage.sessions
@lifecycle.storage.checkpoints
def state_storage():
    """Share one durable backend across its two explicit responsibilities."""

    return state

Queued work also needs @lifecycle.storage.tasks; recurring work needs the same provider under @lifecycle.storage.cron. See Task and cron storage. An unfinished @task awaited inside @tool(durable=True) shares the Harnest run and continuation represented by its A2A Task. On GetTask or subscription, Harnest reconciles a durable result without replaying the original tool call. A2A contextId maps to the Harnest session. Text agents accept text parts; typed-input agents require one structured data part. Tool arguments and results stay private. Configure optional reasoning, decision, and metadata events through Output policy; see A2A event fields. When OutputPolicy(agent_metadata=AgentMetadataMode.RAW) is enabled, streaming metadata updates also carry the native ADK or LangGraph raw mapping. A remote A2A task store or consumer may retain those values. Keep the normalized default unless every A2A caller is authorized to receive provider metadata. CancelTask succeeds after the owned run becomes terminal and any queued-task lease is invalidated. It cannot undo external side effects.

Human approvals and client-tool requests are process-local. If a durable run resumes into one of those interactions on a replica that does not own it, Harnest fails the A2A Task rather than advertising input that replica cannot accept.

Apply security and protocol limits

A2A routes use the root authentication pipeline. Security requirements in agent-card.yaml advertise the contract; an @lifecycle.authenticate extension enforces it. Agent Card discovery remains public. Task IDs are scoped to the compiled application and authenticated user; another user receives 404 rather than task-existence information. Harnest does not currently serve gRPC bindings, push notifications, extended Agent Cards, or A2A extensions. Server startup rejects a card that asks the runtime to claim unsupported behavior.

Call this agent from Harnest

Use the lazy client directly or compose the endpoint as a portable remote agent.

Overview

Get started

Harnest Studio

Guides

API reference

Serve an agent through A2A

Understand when a Task exists

Persist A2A Tasks

Apply security and protocol limits

Call this agent from Harnest

​Understand when a Task exists

​Persist A2A Tasks

​Apply security and protocol limits

Call this agent from Harnest

Understand when a Task exists

Persist A2A Tasks

Apply security and protocol limits