Add your first agent

An agent is an AI model you give instructions and tools. You send it a message and it answers, calling a tool when the task needs one. Stackbone keeps the whole conversation, so every new turn starts from everything said before.

Use an agent for open-ended work: answering questions, walking someone through a task, or picking a tool based on what was asked. You don't script what it does next; the model decides from what you said.

Add one to your workspace

Add an agent to the workspace you already have:

stackbone add agent hello

The command writes one new file, deep-agents/hello/index.ts. Open it and you can read the whole agent in one screen: its name, the model it calls, and one example tool that adds two numbers.

It also adds any runtime package the agent needs to your workspace's package.json. A workspace from stackbone init already pins all of them, so there is usually nothing new to install.

The instruction the agent follows lives outside that file. It is a prompt of its own, keyed by the agent's name, and you write it in the dashboard. Until you do, the agent answers with an empty instruction, so it replies but has no persona yet.

If stackbone dev is still running from the last page, it discovers the new folder on its own and you can skip ahead. If not, install and start:

pnpm install
stackbone dev

See it in the dashboard

Open the Open Studio link that stackbone dev printed. Studio is the dashboard for your workspace, and this link opens it pointed at the one running on your laptop. From the left menu, open Catalog. Your new agent is already there:

The Catalog, read live from the workspace on your laptop.

Chat with it

Open Playground, also in the left menu: it lists every agent and workflow the workspace exposes. Pick your agent, type a message, and press Enter. The reply streams back in a few seconds:

A message and its reply in the Playground.

Ask it to add two numbers. It calls the example tool instead of doing the arithmetic itself, which is the shortest way to see a tool call happen.

Or send a message from the terminal. Your workspace speaks the same wire format as the OpenAI API, so curl works. Name your agent in the model field:

curl -N -X POST http://127.0.0.1:4242/openai/v1/chat/completions \
  -H 'authorization: Bearer dev' \
  -H 'content-type: application/json' \
  -d '{"model":"hello","messages":[{"role":"user","content":"hi"}],"stream":true}'

The reply streams back in the terminal. The header has to be there, but stackbone dev authenticates nobody, so the value is not read on your laptop. A deployed box reads it: the credential there is a workspace API key, minted in Studio under Settings → API keys. See the chat wires before you put a box on a public address.

Write its instruction

Open your agent in Catalog and find its Prompts panel. The key named after the agent, hello, is the instruction it reads on every turn. Write the text, then publish it. Writing and publishing are two steps, so nothing reaches the agent until you publish.

Publishing rebuilds the agent in place, with no restart and no redeploy. Chat again and the next reply follows what you published. Where the instruction lives covers pointing an agent at a different key and filling placeholders with values.

You now have a working agent. Edit deep-agents/hello/index.ts to change the model or add a tool, and stackbone dev re-bundles it as you save.

Press Ctrl+C in the terminal running stackbone dev to stop everything. Run it again whenever you want to pick back up.

What's next

• Add your first workflow: add a job that runs in steps and finishes on its own.