Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions docs/guide/conversations.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ A2A groups messages in two ways. A **task** is one unit of work: it runs, may st

| Command | What it does |
|---|---|
| `a2a send --task-id <id> "..."` | Answers a task that waits for input. |
| `a2a send --task-id <id> "..."` or `--data-part '{...}'` | Answers a task that waits for input; follow its resume hint. |
| `a2a send --context-id <id> "..."` | Starts a new task in the same conversation. |
| `a2a chat` | Holds an interactive conversation. |

Expand Down Expand Up @@ -33,14 +33,17 @@ Task: 01a1d530-540a-791c-a4be-890667492c6a
Context: 01a1d530-540a-79b9-a234-eae4bf4a02f2
Status: input-required (2026-11-13T13:54:36Z)
Permission required: git push (git push origin main).
Reply with one of: once, always, reject.

Resume: a2a send --task-id 01a1d530-540a-791c-a4be-890667492c6a "<reply>"
Resume: a2a send --task-id 01a1d530-540a-791c-a4be-890667492c6a --data-part '{"option":"<option>","seq":1}'
```

```bash
a2a send -a localhost:8080 --task-id 01a1d530-540a-791c-a4be-890667492c6a "once"
a2a send -a localhost:8080 --task-id 01a1d530-540a-791c-a4be-890667492c6a --data-part '{"option":"once","seq":1}'
```

Replace `<option>` with one of the values in the question. Preserve `seq` from the actual hint, including when retrying an answer, so a delayed reply cannot answer a later question.

A task in `auth-required` needs credentials first; see [Credentials](credentials.md).

## Chat
Expand Down
7 changes: 5 additions & 2 deletions docs/reference/output.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,18 +77,21 @@ Artifacts:
| `Artifacts:` | When the task has artifacts. One line each: `[<name>]`, or `[<artifact ID>]` without a name, then the artifact's content |
| `History:` | When the task carries history. One line per message: `[user]` or `[agent]`, then the content |

A task in `input-required` or `auth-required` is followed by a command to reply with, after two blank lines:
A task in `input-required` or `auth-required` is followed by a command to reply with, after two blank lines. For Structured Input object schemas with top-level constants, the hint preserves those constants in a `--data-part` template:

```text
Task: 01a1d53b-390a-762e-bf38-be8aa98a2e7e
Context: 01a1d53b-390a-76d6-879b-6505620790be
Status: input-required (2026-11-13T14:06:30Z)
Permission required: git push (git push origin main).
Reply with one of: once, always, reject.


Resume: a2a send --task-id 01a1d53b-390a-762e-bf38-be8aa98a2e7e "<reply>"
Resume: a2a send --task-id 01a1d53b-390a-762e-bf38-be8aa98a2e7e --data-part '{"option":"<option>","seq":1}'
```

Replace `<option>` with an allowed value from the question. Keep the constants, including `seq`, unchanged when retrying the same answer. The sequence shown here is an example; use the value in the actual hint. Tasks without a supported schema, schemas with malformed top-level fields, and `auth-required` tasks retain the plain-text `"<reply>"` hint.

A message is one line: `[agent] <content>` or `[user] <content>`.

A status update is `[status] <state>`, with `: <message content>` when the update carries a message:
Expand Down
53 changes: 53 additions & 0 deletions internal/cli/cli_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -833,6 +833,59 @@ func TestSend_ResumeHintForInputRequiredTask(t *testing.T) {
}
}

func TestSend_NumberedResumeReplyCanBeRetried(t *testing.T) {
t.Parallel()

var mu sync.Mutex
question := 1
server := httptest.NewServer(a2asrv.NewRESTHandler(a2asrv.NewHandler(
a2asrv.AgentExecutorFunc(func(ctx context.Context, ec *a2asrv.ExecutorContext) iter.Seq2[a2a.Event, error] {
return func(yield func(a2a.Event, error) bool) {
mu.Lock()
defer mu.Unlock()
for _, part := range ec.Message.Parts {
data, ok := part.Data().(map[string]any)
if ok && data["option"] == "once" && data["seq"] == float64(question) {
question++
}
}
part := a2a.NewDataPart(map[string]any{
"type": "object",
"properties": map[string]any{
"option": map[string]any{"type": "string"},
"seq": map[string]any{"const": question},
},
"required": []string{"option"},
})
part.Metadata = map[string]any{
"https://github.com/a2aproject/experimental-ext-structured-input/tree/main/v1": map[string]any{"type": "input_schema"},
}
yield(&a2a.Task{ID: ec.TaskID, ContextID: ec.ContextID, Status: a2a.TaskStatus{
State: a2a.TaskStateInputRequired, Message: &a2a.Message{Parts: a2a.ContentParts{part}},
}}, nil)
}
}),
)))
t.Cleanup(server.Close)

out := mustRunCMD(t, "send", "-e", server.URL, "--transport", "rest", "hello")
_, hint, found := strings.Cut(out, "Resume: a2a send --task-id ")
if !found {
t.Fatalf("send output = %q, want resume hint", out)
}
taskID, data, found := strings.Cut(strings.TrimSpace(hint), " --data-part '")
if !found || !strings.HasSuffix(data, "'") {
t.Fatalf("resume hint = %q, want structured reply", hint)
}
reply := strings.ReplaceAll(strings.TrimSuffix(data, "'"), "<option>", "once")
for range 2 {
out = mustRunCMD(t, "send", "-e", server.URL, "--transport", "rest", "--task-id", taskID, "--data-part", reply)
if !strings.Contains(out, `--data-part '{"option":"<option>","seq":2}'`) {
t.Fatalf("retried send output = %q, want question 2 still waiting", out)
}
}
}

func TestSendWithVersionSelector(t *testing.T) {
t.Parallel()
url := startTestServer(t)
Expand Down
6 changes: 6 additions & 0 deletions internal/output/output.go
Original file line number Diff line number Diff line change
Expand Up @@ -344,6 +344,12 @@ func formatResumeHint(task *a2a.Task) string {
if task.Status.State != a2a.TaskStateInputRequired && task.Status.State != a2a.TaskStateAuthRequired {
return ""
}
if task.Status.State == a2a.TaskStateInputRequired {
if data := structuredResumeData(task.Status.Message); data != "" {
quoted := "'" + strings.ReplaceAll(data, "'", "'\"'\"'") + "'"
return fmt.Sprintf("\n\nResume: a2a send --task-id %s --data-part %s\n", task.ID, quoted)
}
}
return fmt.Sprintf("\n\nResume: a2a send --task-id %s %q\n", task.ID, "<reply>")
}

Expand Down
88 changes: 88 additions & 0 deletions internal/output/output_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -16,13 +16,101 @@ package output

import (
"bytes"
"encoding/json"
"strings"
"testing"

"github.com/google/go-cmp/cmp"

"github.com/a2aproject/a2a-go/v2/a2a"
)

func TestPrintEventStructuredResume(t *testing.T) {
t.Parallel()

tests := []struct {
name string
schema string
want string
}{
{
name: "numbered approval",
schema: `{"type":"object","properties":{"option":{"type":"string"},"seq":{"const":2}},"required":["option"]}`,
want: `--data-part '{"option":"<option>","seq":2}'`,
},
{
name: "generic constants including null and false",
schema: `{"type":"object","properties":{"answer":{"type":"string"},"nonce":{"const":"question-2"},"empty":{"const":null},"enabled":{"const":false}},"required":["answer"]}`,
want: `--data-part '{"answer":"<answer>","empty":null,"enabled":false,"nonce":"question-2"}'`,
},
{
name: "required constant is not replaced with a placeholder",
schema: `{"type":"object","properties":{"seq":{"const":2}},"required":["seq"]}`,
want: `--data-part '{"seq":2}'`,
},
{
name: "schema without constants retains text reply",
schema: `{"type":"object","properties":{"option":{"type":"string"}},"required":["option"]}`,
want: `"<reply>"`,
},
{
name: "array schema retains text reply",
schema: `{"type":"array","properties":{"seq":{"const":2}}}`,
want: `"<reply>"`,
},
{
name: "malformed properties retains text reply",
schema: `{"type":"object","properties":[],"required":["seq"]}`,
want: `"<reply>"`,
},
{
name: "malformed required retains text reply",
schema: `{"type":"object","properties":{"seq":{"const":2}},"required":"seq"}`,
want: `"<reply>"`,
},
{
name: "non-object property is skipped",
schema: `{"type":"object","properties":{"seq":{"const":2},"ignored":[],"option":{"type":"string"}},"required":["option"]}`,
want: `--data-part '{"option":"<option>","seq":2}'`,
},
{
name: "apostrophes and shell substitutions remain literal",
schema: `{"type":"object","properties":{"nonce":{"const":"it's $HOME ` + "`id`" + `"}}}`,
want: `--data-part '{"nonce":"it'"'"'s $HOME ` + "`id`" + `"}'`,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
t.Parallel()
var schema any
if err := json.Unmarshal([]byte(tt.schema), &schema); err != nil {
t.Fatalf("json.Unmarshal() error = %v, want nil", err)
}
part := a2a.NewDataPart(schema)
part.Metadata = map[string]any{
"https://github.com/a2aproject/experimental-ext-structured-input/tree/main/v1": map[string]any{"type": "input_schema"},
}
task := &a2a.Task{ID: "task-1", Status: a2a.TaskStatus{State: a2a.TaskStateInputRequired, Message: &a2a.Message{Parts: a2a.ContentParts{part}}}}
var out bytes.Buffer
printer := NewPrinter(&out, ModeText)
if err := printer.PrintEvent(task); err != nil {
t.Fatalf("Printer.PrintEvent() error = %v, want nil", err)
}
if !strings.HasPrefix(out.String(), "Task: task-1\nStatus: input-required\n") {
t.Fatalf("Printer.PrintEvent() = %q, want task and status before resume hint", out.String())
}
_, got, found := strings.Cut(out.String(), "Resume: ")
if !found {
t.Fatalf("Printer.PrintEvent() = %q, want resume hint", out.String())
}
want := "a2a send --task-id task-1 " + tt.want + "\n"
if diff := cmp.Diff(want, got); diff != "" {
t.Fatalf("Printer.PrintEvent() wrong result (-want +got) diff = %s", diff)
}
})
}
}

func TestPrintTable(t *testing.T) {
t.Parallel()

Expand Down
94 changes: 94 additions & 0 deletions internal/output/structured_input.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
// Copyright 2026 The A2A Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package output

import (
"bytes"
"encoding/json"
"strings"

"github.com/a2aproject/a2a-go/v2/a2a"
)

const structuredInputURI = "https://github.com/a2aproject/experimental-ext-structured-input/tree/main/v1"

// structuredResumeData returns a --data-part reply template that keeps the
// constants of the message's Structured Input schema, or "" when the schema
// has none or can't be read.
func structuredResumeData(message *a2a.Message) string {
if message == nil {
return ""
}
var schemaPart *a2a.Part
for _, part := range message.Parts {
if part == nil {
continue
}
metadata, ok := part.Metadata[structuredInputURI].(map[string]any)
if !ok || metadata["type"] != "input_schema" {
continue
}
if schemaPart != nil {
return ""
}
schemaPart = part
}
if schemaPart == nil {
return ""
}
encoded, err := json.Marshal(schemaPart.Data())
if err != nil {
return ""
}
var schema struct {
Type any `json:"type"`
Properties map[string]json.RawMessage `json:"properties"`
Required []string `json:"required"`
}
if err := json.Unmarshal(encoded, &schema); err != nil {
return ""
}
if schema.Type != nil {
if kind, ok := schema.Type.(string); !ok || kind != "object" {
return ""
}
}
values := make(map[string]any)
for name, property := range schema.Properties {
var keywords map[string]json.RawMessage
if err := json.Unmarshal(property, &keywords); err != nil {
continue
}
if value, ok := keywords["const"]; ok {
values[name] = value
}
}
if len(values) == 0 {
return ""
}
for _, name := range schema.Required {
if _, constant := values[name]; constant {
continue
}
values[name] = "<" + name + ">"
Comment thread
vathuluri marked this conversation as resolved.
Resolved
}
var out bytes.Buffer
encoder := json.NewEncoder(&out)
encoder.SetEscapeHTML(false)
if err := encoder.Encode(values); err != nil {
return ""
}
return strings.TrimSuffix(out.String(), "\n")
}
6 changes: 4 additions & 2 deletions lessons/04-conversations/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,13 +70,13 @@ Status: input-required (2026-11-13T13:54:36Z)
Permission required: bash (whoami).
Reply with one of: once, always (allows bash whoami * in this conversation), reject. ...

Resume: a2a send --task-id 01a1d530-540a-791c-a4be-890667492c6a "<reply>"
Resume: a2a send --task-id 01a1d530-540a-791c-a4be-890667492c6a --data-part '{"option":"<option>","seq":1}'
```

The status message is the agent's question, and `Resume` is the command to answer it. This time you continue the **task**, so the answer goes to the question:

```bash
a2a send --task-id 01a1d530-540a-791c-a4be-890667492c6a once
a2a send --task-id 01a1d530-540a-791c-a4be-890667492c6a --data-part '{"option":"once","seq":1}'
```

```text
Expand All @@ -89,6 +89,8 @@ Artifacts:

`once` allows this one command. `reject` refuses it, and the agent carries on without it.

Choose `<option>` from the values listed in the question and copy `seq` from its actual hint. Keep the same `seq` when retrying the answer: it identifies that question, so a delayed retry cannot approve the next one.

Agents can also stop in `auth-required`, when they need credentials you haven't given. Lesson 5 covers credentials.

## Step 4: Chat
Expand Down
7 changes: 7 additions & 0 deletions skills/a2a-cli/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -112,6 +112,13 @@ transport) or `-e <url> --transport <rest|jsonrpc|grpc>` (connect directly).
a2a send -a https://agent.example.com --task-id <task-id> "Yes, proceed"
```

When `Resume:` includes `--data-part`, fill in its `<field>` placeholders
and keep the other values unchanged. These are constants from the question's
Structured Input schema, such as its question number (`seq`). Retry the same
answer with the same constants after a timeout; fetching a newer question
and replacing them could answer a different question. The displayed JSON
uses POSIX shell quoting; pass it as one argument in other shells.

6. **Continue the conversation** as a new task in the same context:

```bash
Expand Down
7 changes: 4 additions & 3 deletions tools/demo/scenarios/04-conversations.sh
Original file line number Diff line number Diff line change
Expand Up @@ -64,9 +64,10 @@ scene() {
run B 'a2a send "Run whoami and tell me the user name."'
expect_status B input-required
pause 3
local task
task="$(last_match B 'a2a send --task-id [^ ]+')"
run B "a2a send --task-id ${task##* } once"
local resume task
resume="$(last_match B "a2a send --task-id [^ ]+ --data-part '[^']+'")"
task="${resume#a2a send --task-id }"
run B "a2a send --task-id ${task/<option>/once}"
expect_status B completed
pause 3

Expand Down
Loading