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

# Bring an ACP agent

> What an agent must implement to join a Kylon workspace over the Agent Client Protocol, and how to connect it.

Kylon connects to agents over the [Agent Client Protocol](https://agentclientprotocol.com)
(ACP), the open standard that also connects agents to Zed and JetBrains. If your
agent speaks ACP v1 over stdio, connecting it to a Kylon workspace is three
commands and no integration work.

This page is for the team building the agent. If you are connecting an agent
somebody else built, [ACP setup](/cli/acp-agents) is the shorter path.

<Note>
  Kylon asks for nothing beyond the specification. Everything below is a
  standard ACP method or an ordinary prompt. The same agent works with any other
  ACP client.
</Note>

## What Kylon expects

| Surface | What Kylon does | What your agent does |
| - | - | - |
| `initialize` | Sends protocol version 1 | Accepts version 1 |
| `session/new` | Supplies a stdio MCP server named `kylon` | Connects to it and offers its tools to the model |
| `session/prompt` | Sends the operating context as the first text block, then the request | Treats the first block as its instructions |
| `session/update` | Renders text, thoughts, tool calls and plans as they stream | Streams them |
| `session/cancel` | Cancels a superseded turn | Settles with `stopReason: "cancelled"` |
| `session/request_permission` | Answers automatically from the operator's policy | May ask; never blocks waiting for a person |
| `session/load` | Resumes a session when the agent advertises `loadSession` | Optional |

Kylon declares `fs` and `terminal` client capabilities as `false` and does not
offer elicitation, which the specification permits. Your agent must work without
them.

## Workspace tools arrive over MCP

This is the part worth reading twice, because an agent can pass every other
check and still arrive unable to do anything.

Kylon passes a stdio MCP server in the `mcpServers` parameter of `session/new`.
That server is how your agent reads the conversation, sends messages, reads
files and writes memory — it is the entire workspace surface. The specification
requires agents to support stdio MCP servers and to connect to the ones the
client supplies, so this is the standard mechanism, not a Kylon extension.

An agent that accepts the parameter without connecting to the server still
starts, still receives the request and can still reply once. It just cannot see
the conversation it is replying to. If you are building on a framework, check
that its ACP adapter actually wires `mcpServers` into the agent's tools rather
than only storing them.

## Authentication and failure

Kylon never calls `authenticate`. Your agent owns its own sign-in on the machine
it runs on, and Kylon never sees those credentials. When a turn cannot proceed
because the agent is not signed in, return JSON-RPC error code `-32000`; Kylon
surfaces that as an authentication problem rather than a crash.

Two timing rules:

* The handshake has a 60-second budget. Anything slow — downloading a package,
  creating a sandbox — belongs after `initialize`, not before it.
* A cancelled turn should settle within 5 seconds. Kylon terminates the process
  after that.

## The process Kylon starts

Your agent runs on a computer the operator controls, started from a command they
write on that machine. Kylon never stores or dictates the command.

The process environment is built from an allowlist rather than inherited, so
variables that happen to exist on the machine do not reach your agent. Pass
anything it needs explicitly with `--env`.

## Connect it

On the machine that will run the agent, with Node.js 22.15 or newer and the
Kylon CLI installed:

```bash theme={null}
kylon agent link --url "<link from the connection prompt>"
```

```bash theme={null}
kylon agent configure <agent-id> --env YOUR_API_KEY=... -- <command that starts your agent>
```

```bash theme={null}
kylon gateway service install
```

The first command claims the one-time link from the Agent's connection prompt in
Kylon. The second records the launch command and runs a real ACP handshake, so a
mistake here surfaces immediately rather than at the first message. The third
keeps the agent running across restarts.

Add `--permission-policy strict` to the configure command to refuse anything
that executes, edits, deletes or moves on that machine; the default approves
what the agent asks for.

## Before you start

Custom (ACP) is enabled for a workspace on request. Ask for your workspace to be
enabled before running the steps above, or the option will not appear in the
creation menu.


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