Extend

Custom agents

Connect any other agent: an ACP agent, a local program, a web service, an Agent Bridge server, or a Python plugin.

Custom adapters are a community preview. Sleeptalk supports the contract, the starters, and sleeptalk adapter test; it does not certify your agent.

Pick a route

What you have	Profile	You write
An agent that already speaks ACP (Gemini CLI, Goose, Kiro, Qwen Code, Cline, and others)	`type = "command"` with `protocol = "acp"`	Nothing
A program or script on this machine	`type = "command"`	JSON lines in and out
A web service you already run	`type = "http"`	One streaming route
A long-lived remote agent that needs permissions, steering, or reconnects	`type = "bridge"`	An Agent Bridge v1 server
A Python agent that needs the full in-process contract	Your own `type`, from an installed package	A class and a `register()`

If you are not sure, start with command.

Create a starter and test it

Create and check a command agent

sleeptalk adapter new my-agent --kind command
sleeptalk adapter test --config my-agent/sleeptalk.agent.toml --fixture

The starter is an echo agent that already passes every check. Open my-agent/agent.py, replace the marked part of reply with your model call, then test a real turn:

Send a few short real prompts

sleeptalk adapter test --config my-agent/sleeptalk.agent.toml --live

Copy the [agent] section, including [agent.options], into your Sleeptalk profile and start a call.

--kind also takes http, acp, bridge, and python. Add --language node for a Node starter of a command, HTTP, or bridge agent. --dir sets the target folder.

You can also choose My own agent in sleeptalk init. It asks what kind of agent you have, or creates a starter if you have none yet, checks the agent without sending a prompt, and writes the profile. Tokens go to Sleeptalk's private store, and the profile references them under token_env. An older copy in .env still works and moves to the store the next time you save the profile's agent.

Connect an ACP agent

Profile section

[agent]
type = "command"
workspace_dir = "."
permission_mode = "pending"

[agent.options]
protocol = "acp"
command = ["gemini", "--experimental-acp"]
env = ["GEMINI_API_KEY"]

Check your agent's documentation for its ACP command. permission_mode is pending by default, so tool approvals go to the caller. deny refuses them. auto approves each call once, and setup probes refuse it. Permission answers follow the ACP option's kind, so a "no" can never select an allow option.

type = "acp" means Hermes. Use type = "command" for any other ACP agent.

What your agent receives

Command agents get a small base environment (PATH, HOME, locale, proxy, and certificate settings) plus the variable names listed in env. Speech-provider and Discord credentials never pass through. Set inherit_env = true to pass everything else.

HTTP agents cannot receive a message mid-turn, so permissions, clarification, steering, and cancellation are unavailable there. Plain http:// is accepted only on loopback. Put secrets in token_env, never in headers or the URL; setup keeps the token in the private store.

Test levels

Command	What it does
`sleeptalk adapter test --config PROFILE`	Loads and starts the agent. Sends no prompt.
`--fixture`	Sends the starter's test prompts: hello, slow, hang, tool, permission, clarify.
`--live`	Sends a few short real prompts. May spend tokens.
`--json`	Prints one machine-readable report.

The report separates protocol, availability, and voice-quality results. A live test does not exercise permissions, clarification, or steering, and does not prove microphone playback. Custom-agent behavior and permissions remain the author's responsibility.

Common problems

It only says "Still working on it" and never answers. The program is not sending frames Sleeptalk understands. An agent's interactive app run as a plain program is the usual cause; use its ACP entry point with protocol = "acp".
The agent cannot find its API key. Add the variable name to env, or set inherit_env = true.
adapter test passes but a call does not. A plain test sends no prompt. Run it with --live.

The complete guide, with every frame and option, is Bring your own agent. For contracts and conformance, see components and protocols.