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
164 changes: 164 additions & 0 deletions docs/quickstart/a2acli.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,164 @@
# a2acli quickstart

`a2acli` is a command-line client for A2A agents. This page runs its main commands against the greeter from the [agent quickstart](agent/index.md), so start that server first, as [Start the server](agent/start-the-server.md) shows.

The commands run the CLI from a checkout of the repository. With an installed binary, run `a2acli` in place of `cargo run -q --bin a2acli --`. The [command reference](../reference/a2acli.md) covers everything else.

## Name the agent

`a2acli` targets `http://localhost:3000` unless told otherwise, which is the port of the hello world example. The greeter listens on port 9999. Set it once in the environment:

```bash
export A2ACLI_AGENT_CARD=http://localhost:9999
```

You can pass `-a http://localhost:9999` to each command instead. [Naming the agent](../reference/a2acli.md#naming-the-agent) lists the accepted forms.

## Read the card

```bash
cargo run -q --bin a2acli -- card get
```

```text
Name: Greeter
Description: Greets you by name. Asks for the name first if it was not given.
Version: 0.1.0
Streaming: true
Push Notifications: false
Extended Card: false
Interfaces:
- JSONRPC http://localhost:9999/jsonrpc (v1.0)
- HTTP+JSON http://localhost:9999/rest (v1.0)

Skills: 1
```

## Send a message

```bash
cargo run -q --bin a2acli -- send "Ada"
```

```text
Task ID: 01a1d1d2-8b9b-726d-b4e7-4cbf11b62730
Context ID: 01a1d1d2-8b9c-725d-82e1-b1c0096fe0d5
State: COMPLETED
Artifact: greeting
Text:
Hello,

Text:
Ada

Text:
!
```

`send` waits for the task to finish, like the `SendMessage` call in [Call the agent](agent/call-the-agent.md). The greeting is the three text parts of the `greeting` artifact. Your ids will differ.

## Stream the answer

`--stream` prints each event as it arrives. The CLI checks the card before it streams: the agent has to declare `streaming`, and the greeter does.

```bash
cargo run -q --bin a2acli -- send "Grace" --stream
```

```text
Task ID: 01a1d1d2-981d-7375-98a9-728b516995c5
Context ID: 01a1d1d2-981d-7375-98a9-728cc9a6fad1
State: WORKING
Task ID: 01a1d1d2-981d-7375-98a9-728b516995c5
Context ID: 01a1d1d2-981d-7375-98a9-728cc9a6fad1
Artifact: greeting
Text:
Hello,
Task ID: 01a1d1d2-981d-7375-98a9-728b516995c5
Context ID: 01a1d1d2-981d-7375-98a9-728cc9a6fad1
Artifact: greeting
Text:
Grace
Task ID: 01a1d1d2-981d-7375-98a9-728b516995c5
Context ID: 01a1d1d2-981d-7375-98a9-728cc9a6fad1
Artifact: greeting
Text:
!
Task ID: 01a1d1d2-981d-7375-98a9-728b516995c5
Context ID: 01a1d1d2-981d-7375-98a9-728cc9a6fad1
State: COMPLETED
```

## List the tasks

```bash
cargo run -q --bin a2acli -- task list
```

```text
Total: 4
Page Size: 50
Task:
Task ID: 01a1d1d1-344e-72e6-b955-5a334510c629
Context ID: 01a1d1d1-344e-72e6-b955-5a3447cff548
State: COMPLETED

Task:
Task ID: 01a1d1d1-3a35-7721-8f1e-6741ba7aa8e6
Context ID: 01a1d1d1-3a35-7721-8f1e-674234db660e
State: COMPLETED

Task:
Task ID: 01a1d1d2-8b9b-726d-b4e7-4cbf11b62730
Context ID: 01a1d1d2-8b9c-725d-82e1-b1c0096fe0d5
State: COMPLETED

Task:
Task ID: 01a1d1d2-981d-7375-98a9-728b516995c5
Context ID: 01a1d1d2-981d-7375-98a9-728cc9a6fad1
State: COMPLETED
```

The server keeps its tasks in memory, so the list holds every task since it started: yours may be longer than this one.

## When the agent asks for input

Sent only `hello`, the greeter asks for a name and waits. `a2acli` names the state on stderr and prints a command to resume with:

```bash
cargo run -q --bin a2acli -- send "hello"
```

```text
warning: task 01a1d1d2-a7a7-713f-a233-e0a5912b5553: it is paused at INPUT_REQUIRED and needs a reply to continue
Task ID: 01a1d1d2-a7a7-713f-a233-e0a5912b5553
Context ID: 01a1d1d2-a7a7-713f-a233-e0a6e4620d40
State: INPUT_REQUIRED
Text:
Who should I greet?

Resume with: a2acli send --task-id 01a1d1d2-a7a7-713f-a233-e0a5912b5553 "<reply>"
```

Answer with the task ID from your output:

```bash
cargo run -q --bin a2acli -- send --task-id 01a1d1d2-a7a7-713f-a233-e0a5912b5553 "Grace"
```

```text
Task ID: 01a1d1d2-a7a7-713f-a233-e0a5912b5553
Context ID: 01a1d1d2-a7a7-713f-a233-e0a6e4620d40
State: COMPLETED
Artifact: greeting
Text:
Hello,

Text:
Grace

Text:
!
```

The task is the same one, now completed. The exit status of `a2acli` is `0` in both calls: it reports whether the CLI did its job, not whether the task is finished.
3 changes: 2 additions & 1 deletion docs/quickstart/agent/next-steps.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ You wrote an agent with a card, an executor and a server, called it over JSON-RP

## Read on

- [`a2acli`](../../reference/a2acli.md) is a command-line client for A2A agents.
- The [client quickstart](../client.md) calls the agent from Rust.
- The [`a2acli` quickstart](../a2acli.md) calls it from the command line, and the [`a2acli` reference](../../reference/a2acli.md) covers the rest of the CLI.
- The API reference of the crates this page used is on docs.rs: [`a2a-lf`](https://docs.rs/a2a-lf) for the protocol types and [`a2a-server-lf`](https://docs.rs/a2a-server-lf) for the server.
- [a2a-protocol.org](https://a2a-protocol.org/latest/) describes the protocol itself.
49 changes: 49 additions & 0 deletions docs/quickstart/client.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
# Client quickstart

A client reads an agent's card, connects over one of the bindings the card lists, and calls the agent. This page builds one and runs it against the greeter from the [agent quickstart](agent/index.md), so start that server first, as [Start the server](agent/start-the-server.md) shows.

This is the whole client:

```rust title="examples/src/quickstart/client.rs"
--8<-- "examples/src/quickstart/client.rs:imports"

--8<-- "examples/src/quickstart/client.rs:main"
```

## Connect

`AgentCardResolver` fetches the card from `/.well-known/agent-card.json` under the URL. `A2AClientFactory` turns the card into a client: it ranks the card's interfaces against the client's preferred bindings and returns a client for the first transport that connects. JSON-RPC and REST are registered by default, and the `a2a-grpc` and `a2a-slimrpc` crates add the gRPC and SLIM RPC bindings. The greeter's card lists JSON-RPC and REST, so that is what the client talks.

## Send a message

`send_message` waits for the task to finish, or to need input, like the `SendMessage` call in [Call the agent](agent/call-the-agent.md). It returns a `SendMessageResponse`, which is either a `Task` or a `Message`, because an agent may answer with either. The greeter answers with a task, and `greeting` joins the parts of its artifact:

```rust title="examples/src/quickstart/client.rs"
--8<-- "examples/src/quickstart/client.rs:helpers"
```

## Stream a response

`send_streaming_message` returns a stream of events: the task, messages, status updates and artifact updates. The client prints each piece of the greeting as its artifact update arrives, which is the streaming the agent quickstart showed with `curl`.

## Run it

With the server running, in a second terminal:

```bash
cargo run --bin quickstart-client --package examples
```

```text
Connected to Greeter
Completed: Hello, Ada!
Hello, Grace!
```

`Hello, Grace!` appears piece by piece, over about a second and a half. The client takes the agent's URL as an optional argument, for an agent that is not on `localhost:9999`:

```bash
cargo run --bin quickstart-client --package examples -- http://localhost:9999
```

Next, [`a2acli`](a2acli.md) does the same from the command line.
4 changes: 4 additions & 0 deletions examples/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,10 @@ path = "src/helloworld/client.rs"
name = "quickstart-server"
path = "src/quickstart/server.rs"

[[bin]]
name = "quickstart-client"
path = "src/quickstart/client.rs"

[[bin]]
name = "helloworld-tls-server"
path = "src/helloworld_tls/server.rs"
Expand Down
85 changes: 85 additions & 0 deletions examples/src/quickstart/client.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
// Copyright AGNTCY Contributors (https://github.com/agntcy)
// Copyright A2A Contributors (https://github.com/a2aproject)
// SPDX-License-Identifier: Apache-2.0

//! A client for the quickstart agent.
//!
//! Start the agent first:
//! cargo run --bin quickstart-server --package examples
//! Then run this client:
//! cargo run --bin quickstart-client --package examples
//! It takes the agent's URL as an optional argument.

// --8<-- [start:imports]
use std::io::Write;

use a2a::event::StreamResponse;
use a2a::*;
use a2a_client::A2AClientFactory;
use a2a_client::agent_card::AgentCardResolver;
use futures::StreamExt;
// --8<-- [end:imports]

// --8<-- [start:main]
#[tokio::main]
async fn main() -> Result<(), A2AError> {
let url = std::env::args()
.nth(1)
.unwrap_or_else(|| "http://localhost:9999".to_string());

// Fetch the agent card, then let the factory pick a binding from it.
let card = AgentCardResolver::new(None).resolve(&url).await?;
let client = A2AClientFactory::builder()
.build()
.create_from_card(&card)
.await?;
println!("Connected to {}", card.name);

// Send a message and wait for the task to finish.
match client.send_message(&request("Ada")).await? {
SendMessageResponse::Task(task) => {
println!("{:?}: {}", task.status.state, greeting(&task));
}
SendMessageResponse::Message(message) => {
println!("{}", message.text().unwrap_or_default());
}
}

// Send another one and print the answer as it arrives.
let mut events = client.send_streaming_message(&request("Grace")).await?;
while let Some(event) = events.next().await {
if let StreamResponse::ArtifactUpdate(update) = event? {
for part in &update.artifact.parts {
print!("{}", part.as_text().unwrap_or_default());
}
std::io::stdout().flush().ok();
}
}
println!();

Ok(())
}
// --8<-- [end:main]

// --8<-- [start:helpers]
/// A request with one text part.
fn request(text: &str) -> SendMessageRequest {
SendMessageRequest {
message: Message::new(Role::User, vec![Part::text(text)]),
configuration: None,
metadata: None,
tenant: None,
}
}

/// The text of the task's first artifact, the pieces joined.
fn greeting(task: &Task) -> String {
task.artifacts
.iter()
.flatten()
.take(1)
.flat_map(|artifact| &artifact.parts)
.filter_map(Part::as_text)
.collect()
}
// --8<-- [end:helpers]
2 changes: 2 additions & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,8 @@ nav:
- Call the agent: quickstart/agent/call-the-agent.md
- Streaming and multi-turn: quickstart/agent/streaming-and-multi-turn.md
- Next steps: quickstart/agent/next-steps.md
- Client: quickstart/client.md
- a2acli: quickstart/a2acli.md
- Reference:
- a2acli: reference/a2acli.md

Expand Down
Loading