interactions/v1
The A2A extension that carries an Agent's open approval, question, or connection request, and the caller's answer on the same task.
URI: https://docs.nylorun.com/a2a/interactions/v1
{
"status": {
"state": "TASK_STATE_AUTH_REQUIRED",
"message": {
"role": "ROLE_AGENT",
"parts": [{ "text": "Approve github / create_pull_request?" }],
"extensions": ["https://docs.nylorun.com/a2a/interactions/v1"],
"metadata": {
"https://docs.nylorun.com/a2a/interactions/v1": {
"interactionId": "eff_01J…",
"kind": "approval",
"prompt": "Approve github / create_pull_request?",
"detail": { "server": "github", "tool": "create_pull_request" }
}
}
}
}
}A turn pauses when the tool policy holds a tool call for a person, when the agent asks a question, or when it asks for an app to be connected. The task's status message then carries the open interaction under this extension, and the caller answers on the same task.
A client that has not activated the extension sees the same status message as
plain text. Text never approves: a text reply to a task that waits for an
approval is refused with UnsupportedOperationError. A text or data reply to a
question answers it.
The open interaction
On the status message of a task in an interrupted state.
| Field | Type | Meaning |
|---|---|---|
interactionId | string | The interaction to answer. For a held tool call, the effect id. |
kind | approval, question, or connection | What the agent waits for. |
prompt | string | The text to show a person. The status message's text part says the same. |
detail | object, optional | What the interaction is about: a held call's server, tool, and reason, or a connection's app and reason. Never a call's arguments. |
| Kind | Task state | Raised by | Answer with |
|---|---|---|---|
approval | TASK_STATE_AUTH_REQUIRED | The tool policy holding a call | approved: true sends the held call as the person saw it; false fails it to the model as tool.denied |
question | TASK_STATE_INPUT_REQUIRED | The agent asking | value: any JSON value |
connection | TASK_STATE_AUTH_REQUIRED | The agent calling request_connection | value: { "connected": true } once the app is connected; { "connected": false } to decline |
Connections
An agent asks for an app to be connected with request_connection, a
built-in tool of our harness that is off by default. Turn it on in the agent's
AGENT.md:
---
name: coder
description: Writes and ships changes to the team's repositories.
loop:
connections: true
---The tool takes { app, reason }: the app cut at 80 characters, the reason at
280. The turn pauses with the prompt Connect <app>: <reason> and
detail: { app, reason }. The person connects the app wherever your product
keeps its connections, then you answer. { "connected": true }, or true,
tells the model Connected: <app>; any other value tells it
Not connected: <app>. approved: true or false is read the same way. See
AGENT.md.
The answer
A message on the same taskId and contextId, listing the extension:
{
"message": {
"role": "ROLE_USER",
"messageId": "m-2",
"taskId": "t1.…",
"contextId": "ticket-4821",
"parts": [{ "data": { "approved": true } }],
"extensions": ["https://docs.nylorun.com/a2a/interactions/v1"],
"metadata": {
"https://docs.nylorun.com/a2a/interactions/v1": {
"interactionId": "eff_01J…",
"approved": true
}
}
}
}| Field | Type | Meaning |
|---|---|---|
interactionId | string | The open interaction's id. |
approved | boolean | The answer to an approval. For a question or a connection, it is read as the value. |
value | any JSON | The answer to a question or a connection. For an approval, a boolean value is read as approved. |
An approval is the Runtime's approve command, and a question or connection
its respond command, as on
Pauses and control. The Runtime records
the caller's subject as approvedBy. The messageId is the answer's
idempotency key: a retry with the same id answers once. Answered, the task
returns to TASK_STATE_WORKING on the same taskId.
With the SDK:
await a2a.answer({
taskId: task.id,
contextId: task.contextId,
interactionId,
approved: true,
messageId: `answer:${interactionId}`,
});See A2A client.