> ## Documentation Index
> Fetch the complete documentation index at: https://usefused.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# harnest.a2a

> Public Python signatures, fields, and methods.

[All Python modules](https://usefused.com/docs/harnest/reference/api/overview.md) · [Import and compatibility guidance](https://usefused.com/docs/harnest/build/python-imports.md)

## Client operations

| Method | Network behavior |
| - | - |
| `connect()` | Fetch and validate the Agent Card once |
| `send(...)` | Send one message; optionally poll only the returned Task |
| `stream(...)` | Stream one new interaction; requires `streaming=True` on the client |
| `get_task(task_id)` | Fetch one explicitly named Task |
| `list_tasks(...)` | Fetch one bounded, filtered page on request |
| `cancel_task(task_id)` | Request cancellation of one explicitly named Task |
| `subscribe(task_id)` | Subscribe to one existing Task |

## A2A event fields

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)`](https://usefused.com/docs/harnest/reference/api/output#outputpolicy), 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.

## Exports

| Name | Kind |
| - | - |
| [`A2AClient`](#a2aclient) | Class |
| [`A2AClientError`](#a2aclienterror) | Class |
| [`A2AResult`](#a2aresult) | Class |
| [`A2AUpdate`](#a2aupdate) | Class |
| [`RemoteAgent`](#remoteagent) | Class |
| [`RemoteAgentError`](#remoteagenterror) | Class |

## A2AClient

Discover and invoke one remote agent without background polling or listing.

```python theme={null}
A2AClient(
    card_url: str,
    *,
    card: Mapping[str, Any] | None = None,
    timeout: float = 300,
    poll_interval: float = 0.5,
    streaming: bool = False,
    allowed_hosts: Sequence[str] = (),
    allow_insecure: bool = False,
    http_client: httpx.AsyncClient | None = None,
) -> None
```

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `card_url` | `str` | Required |
> | `card` | `Mapping[str, Any] \| None` | `None` |
> | `timeout` | `float` | `300` |
> | `poll_interval` | `float` | `0.5` |
> | `streaming` | `bool` | `False` |
> | `allowed_hosts` | `Sequence[str]` | `()` |
> | `allow_insecure` | `bool` | `False` |
> | `http_client` | `httpx.AsyncClient \| None` | `None` |
>
> ```python theme={null}
> from harnest.a2a import A2AClient
>
> client = A2AClient(card_url=...)
> ```

### A2AClient.card

Return the validated cached card without triggering network I/O.

> [accordion] Example
>
> ```python theme={null}
> from harnest.a2a import A2AClient
>
> client: A2AClient
> value = client.card
> ```

### A2AClient.connect

```python theme={null}
async A2AClient.connect() -> AgentCard
```

Resolve and validate the Agent Card exactly once for this client.

> [accordion] Example
>
> ```python theme={null}
> from harnest.a2a import A2AClient
>
> client: A2AClient
> result = await client.connect()
> ```

### A2AClient.send

```python theme={null}
async A2AClient.send(
    value: Any,
    *,
    context_id: str | None = None,
    task_id: str | None = None,
    metadata: Mapping[str, Any] | None = None,
    accepted_output_modes: Sequence[str] = (),
    return_immediately: bool = False,
    wait: bool = True,
    credential: Credential | None = None,
) -> A2AResult
```

Send one message and poll only when the caller requested a final result.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `value` | `Any` | Required |
> | `context_id` | `str \| None` | `None` |
> | `task_id` | `str \| None` | `None` |
> | `metadata` | `Mapping[str, Any] \| None` | `None` |
> | `accepted_output_modes` | `Sequence[str]` | `()` |
> | `return_immediately` | `bool` | `False` |
> | `wait` | `bool` | `True` |
> | `credential` | `Credential \| None` | `None` |
>
> ```python theme={null}
> from harnest.a2a import A2AClient
>
> client: A2AClient
> result = await client.send(value=...)
> ```

### A2AClient.stream

```python theme={null}
A2AClient.stream(
    value: Any,
    *,
    context_id: str | None = None,
    task_id: str | None = None,
    metadata: Mapping[str, Any] | None = None,
    credential: Credential | None = None,
) -> AsyncIterator[A2AUpdate]
```

Yield remote updates without issuing any implicit follow-up operations.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `value` | `Any` | Required |
> | `context_id` | `str \| None` | `None` |
> | `task_id` | `str \| None` | `None` |
> | `metadata` | `Mapping[str, Any] \| None` | `None` |
> | `credential` | `Credential \| None` | `None` |
>
> ```python theme={null}
> from harnest.a2a import A2AClient
>
> client: A2AClient
> async for item in client.stream(value=...):
>     ...
> ```

### A2AClient.get\_task

```python theme={null}
async A2AClient.get_task(task_id: str, *, history_length: int = 0, credential: Credential | None = None) -> Task
```

Fetch one task only after an explicit caller request.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `task_id` | `str` | Required |
> | `history_length` | `int` | `0` |
> | `credential` | `Credential \| None` | `None` |
>
> ```python theme={null}
> from harnest.a2a import A2AClient
>
> client: A2AClient
> result = await client.get_task(task_id=...)
> ```

### A2AClient.list\_tasks

```python theme={null}
async A2AClient.list_tasks(
    *,
    page_size: int = 50,
    page_token: str = '',
    context_id: str = '',
    include_artifacts: bool = False,
    credential: Credential | None = None,
) -> ListTasksResponse
```

List a bounded page only when directly requested by application code.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `page_size` | `int` | `50` |
> | `page_token` | `str` | `''` |
> | `context_id` | `str` | `''` |
> | `include_artifacts` | `bool` | `False` |
> | `credential` | `Credential \| None` | `None` |
>
> ```python theme={null}
> from harnest.a2a import A2AClient
>
> client: A2AClient
> result = await client.list_tasks()
> ```

### A2AClient.cancel\_task

```python theme={null}
async A2AClient.cancel_task(task_id: str, *, credential: Credential | None = None) -> Task
```

Cancel one task only in response to explicit local cancellation.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `task_id` | `str` | Required |
> | `credential` | `Credential \| None` | `None` |
>
> ```python theme={null}
> from harnest.a2a import A2AClient
>
> client: A2AClient
> result = await client.cancel_task(task_id=...)
> ```

### A2AClient.subscribe

```python theme={null}
A2AClient.subscribe(task_id: str, *, credential: Credential | None = None) -> AsyncIterator[A2AUpdate]
```

Subscribe to an existing task without fetching or listing others.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `task_id` | `str` | Required |
> | `credential` | `Credential \| None` | `None` |
>
> ```python theme={null}
> from harnest.a2a import A2AClient
>
> client: A2AClient
> async for item in client.subscribe(task_id=...):
>     ...
> ```

### A2AClient.close

```python theme={null}
async A2AClient.close() -> None
```

Close the selected transport or the unused discovery client once.

> [accordion] Example
>
> ```python theme={null}
> from harnest.a2a import A2AClient
>
> client: A2AClient
> await client.close()
> ```

### A2AClient.**aenter**

```python theme={null}
async A2AClient.__aenter__() -> 'A2AClient'
```

> [accordion] Example
>
> ```python theme={null}
> from harnest.a2a import A2AClient
>
> client: A2AClient
> async with client:
>     ...
> ```

### A2AClient.**aexit**

```python theme={null}
async A2AClient.__aexit__() -> None
```

> [accordion] Example
>
> ```python theme={null}
> from harnest.a2a import A2AClient
>
> client: A2AClient
> async with client:
>     ...
> ```

## A2AClientError

An outbound A2A interaction failed Harnest policy or protocol handling.

> [accordion] Example
>
> ```python theme={null}
> from harnest.a2a import A2AClientError
>
> try:
>     ...
> except A2AClientError as error:
>     ...
> ```

## A2AResult

Minimum portable projection of a direct Message or tracked A2A Task.

```python theme={null}
A2AResult(
    text: str,
    data: Any,
    context_id: str | None,
    task_id: str | None,
    state: str,
    message: Message | None = None,
    task: Task | None = None,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `text` | `str` | `—` |
| `data` | `Any` | `—` |
| `context_id` | `str \| None` | `—` |
| `task_id` | `str \| None` | `—` |
| `state` | `str` | `—` |
| `message` | `Message \| None` | `None` |
| `task` | `Task \| None` | `None` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `text` | `str` | Required |
> | `data` | `Any` | Required |
> | `context_id` | `str \| None` | Required |
> | `task_id` | `str \| None` | Required |
> | `state` | `str` | Required |
> | `message` | `Message \| None` | `None` |
> | `task` | `Task \| None` | `None` |
>
> ```python theme={null}
> from harnest.a2a import A2AResult
>
> result = A2AResult(text=..., data=..., context_id=..., task_id=..., state=...)
> ```

### A2AResult.terminal

Return whether the remote interaction no longer needs observation.

> [accordion] Example
>
> ```python theme={null}
> from harnest.a2a import A2AResult
>
> result: A2AResult
> value = result.terminal
> ```

### A2AResult.as\_dict

```python theme={null}
A2AResult.as_dict() -> dict[str, Any]
```

Serialize only portable output and opaque task references.

> [accordion] Example
>
> ```python theme={null}
> from harnest.a2a import A2AResult
>
> result: A2AResult
> result = result.as_dict()
> ```

## A2AUpdate

One normalized outbound stream update without protobuf coupling.

```python theme={null}
A2AUpdate(
    kind: str,
    task_id: str | None,
    context_id: str | None,
    state: str | None = None,
    text: str = '',
    data: Any = None,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `kind` | `str` | `—` |
| `task_id` | `str \| None` | `—` |
| `context_id` | `str \| None` | `—` |
| `state` | `str \| None` | `None` |
| `text` | `str` | `''` |
| `data` | `Any` | `None` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `kind` | `str` | Required |
> | `task_id` | `str \| None` | Required |
> | `context_id` | `str \| None` | Required |
> | `state` | `str \| None` | `None` |
> | `text` | `str` | `''` |
> | `data` | `Any` | `None` |
>
> ```python theme={null}
> from harnest.a2a import A2AUpdate
>
> update = A2AUpdate(kind=..., task_id=..., context_id=...)
> ```

## RemoteAgent

A first-class remote A2A participant usable as a portable graph node.

```python theme={null}
RemoteAgent(
    name: str,
    card_url: str,
    description: str = '',
    audience: str | None = None,
    scopes: tuple[str, ...] = (),
    timeout: float = 300,
    allowed_hosts: tuple[str, ...] = (),
    allow_insecure: bool = False,
    card: Mapping[str, Any] | None = None,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `name` | `str` | `—` |
| `card_url` | `str` | `—` |
| `description` | `str` | `''` |
| `audience` | `str \| None` | `None` |
| `scopes` | `tuple[str, ...]` | `()` |
| `timeout` | `float` | `300` |
| `allowed_hosts` | `tuple[str, ...]` | `()` |
| `allow_insecure` | `bool` | `False` |
| `card` | `Mapping[str, Any] \| None` | `None` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `name` | `str` | Required |
> | `card_url` | `str` | Required |
> | `description` | `str` | `''` |
> | `audience` | `str \| None` | `None` |
> | `scopes` | `tuple[str, ...]` | `()` |
> | `timeout` | `float` | `300` |
> | `allowed_hosts` | `tuple[str, ...]` | `()` |
> | `allow_insecure` | `bool` | `False` |
> | `card` | `Mapping[str, Any] \| None` | `None` |
>
> ```python theme={null}
> from harnest.a2a import RemoteAgent
>
> agent = RemoteAgent(name=..., card_url=...)
> ```

### RemoteAgent.**call**

```python theme={null}
async RemoteAgent.__call__(value: Any, *, context: GraphContext) -> Event
```

Delegate one graph value and retain only opaque conversation references.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `value` | `Any` | Required |
> | `context` | `GraphContext` | Required |
>
> ```python theme={null}
> from harnest.a2a import RemoteAgent
>
> agent: RemoteAgent
> event = await agent(value=..., context=...)
> ```

### RemoteAgent.as\_tool

```python theme={null}
RemoteAgent.as_tool() -> Any
```

Expose delegation as an explicit text tool when agent semantics are unsuitable.

> [accordion] Example
>
> ```python theme={null}
> from harnest.a2a import RemoteAgent
>
> agent: RemoteAgent
> result = agent.as_tool()
> ```

## RemoteAgentError

A remote agent reached a terminal failure state.

> [accordion] Example
>
> ```python theme={null}
> from harnest.a2a import RemoteAgentError
>
> try:
>     ...
> except RemoteAgentError as error:
>     ...
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.