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 .

Clients discover the same compiled card at GET /.well-known/agent-card.json. Use JSONRPC instead of HTTP+JSON when that binding fits the client ecosystem better. Author A2A 1.0 for new integrations; Harnest also accepts protocol version 0.3 for compatibility on these two HTTP bindings. 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:

import os

from harnest.store import PostgresStore

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

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

When a compiled project also contains @task work, register an explicit @lifecycle.storage.tasks provider. Sessions and checkpoints do not implicitly configure queued work. PostgreSQL, Redis, and custom providers can persist the queue; see Task and cron storage. Recurring work also requires the same provider under @lifecycle.storage.cron. 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. The A2A contextId maps to the Harnest session ID. A text-input root accepts A2A text parts; a typed-input root requires exactly one structured data part. Harnest projects customer-visible text and structured results back to A2A parts while keeping tool arguments and results inside the executing agent boundary regardless of tool_activity. With OutputPolicy(thinking=True), a streaming Task emits provider-exposed reasoning as a working-status message whose metadata.harnest.type is thinking; reasoning is otherwise suppressed. Agent and graph-node lifecycle updates use the same working status with metadata.harnest.type: agent_activity; model metadata uses metadata.harnest.type: agent_metadata. Set agent_metadata=AgentMetadataMode.SUPPRESS to omit those updates and aggregate token counts from the final Message or Task artifact. Answer artifacts can carry metadata.harnest.agent attribution. With OutputPolicy(decision_results=True), streaming tasks also publish working-status metadata with metadata.harnest.type: decision_result and the typed decision in metadata.harnest.value. Decision results are hidden by default. 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 reports success only after Harnest has made the owned run and continuation terminal. For a queued @task, cancellation also invalidates its execution lease and removes its private payload in task storage before committing the A2A CANCELED snapshot. Cancellation cannot undo external side effects already performed by the task.

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

Guides

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