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: the model, the instructions, 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.

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: pick your agent in the target picker at the top, 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. A local stackbone dev accepts any bearer token, so that header only starts to matter once the same agent runs on a server.

You now have a working agent. Edit the instructions in deep-agents/hello/index.ts and chat again; the next reply follows what you wrote.

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.