Tutorial: your first ACP exchange with a test agent

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104

# Tutorial: your first ACP exchange with a test agent

By the end of this tutorial, you will have sent two messages to Alice, one of the project's test agents, over the Agent Client Protocol, read the streamed answers, and found the recorded JSON-RPC traffic. This is the conversation Sidekicks will have with every agent; there is no application yet, so we use the small client written for the ACP spike.

## Prerequisites

- The repository cloned, and a terminal open at its root.
- Go 1.26 or newer (`go version`).
- `mm` v1.0.3 installed and on your `PATH` (`mm -version`). If it lives elsewhere, set `MM_BIN=/path/to/mm`.
- [llmman](https://llmmanorg.github.io/) running on this machine, with Alice's model pulled: `llmman pull hf.co/unsloth/gemma-4-E2B-it-GGUF:Q4_K_M`.
- `jq` (`jq --version`).

## Step 1 — Look at what is running

Type:

```bash
scripts/agents.sh ps
```

You should see:

```text
agents running (limit 2):
models loaded:
```

No agent runs and no model is loaded: the machine is ready.

## Step 2 — Talk to Alice

Type:

```bash
cd spikes/acp-trace
go run . -agent alice -out /tmp/alice.jsonl \
    -prompt "Bonjour, qui es-tu ? Réponds en une phrase." \
    -prompt "Écris un bloc de code Go qui affiche hello."
```

The first run downloads the ACP library, then the model loads, which takes a few seconds. You should see, among a few `[acp]` lines written by mm:

~~~text
== agent: &{… Name:Alice … Version:v1.0.3}
== protocol version: 1
== session: 20261029-082808-9a7c173b

>> Bonjour, qui es-tu ? Réponds en une phrase.

[commands] 3 available
Je suis Gemma 4, un grand modèle linguistique développé par Google DeepMind.
== stop reason: end_turn

>> Écris un bloc de code Go qui affiche hello.
```go
package main
…
== stop reason: end_turn
unloaded: hf.co/unsloth/gemma-4-E2B-it-GGUF:Q4_K_M
~~~

Your session id and Alice's wording will differ: the model chooses its words. We have just done what Sidekicks does for every message: a handshake (`initialize`), a session (`session/new`), two prompts, and the answers streamed word by word.

## Step 3 — Check that the memory was freed

Go back to the root and type:

```bash
cd ../..
scripts/agents.sh ps
```

You should see the same empty lists as in step 1. The last line of step 2, `unloaded: …`, was the script freeing Alice's model as soon as the agent stopped.

## Step 4 — Read the traffic

Type:

```bash
jq -r '.dir + "  " + (.msg.params.update.sessionUpdate // .msg.method // "response")' /tmp/alice.jsonl | head -8
```

You should see:

```text
client→agent  initialize
agent→client  response
client→agent  session/new
agent→client  response
agent→client  available_commands_update
client→agent  session/prompt
agent→client  agent_message_chunk
agent→client  agent_message_chunk
```

Each line is one JSON-RPC message. Right after the session is created, Alice announces the available commands; the answer you read in step 2 is made of many `agent_message_chunk` messages.

## What now?

You have driven a real agent over ACP and seen exactly what goes over the wire. To go further:

- Start test agents in other situations → [How to run a test agent](../how-to/run-a-test-agent.md)
- Every command of the script → [Reference: scripts/agents.sh](../reference/agents-script.md)
- Why Sidekicks speaks ACP, and what the spike learnt → [Why ACP](../explanation/why-acp.md)