---
title: 'Add your first agent'
description: 'Add an agent to your workspace, start it, and chat with it in the dashboard.'
position: 4
---

# 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:

```sh
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:

```sh
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 in Studio, listing the agents and workflows in your workspace.](/images/first-steps/studio-agents.png)
_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:

![The Playground in Studio, showing a message sent to an agent and its reply.](/images/first-steps/playground-chat.png)
_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:

```sh
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](/docs/home/get-started/first-workflow)**: add a job
  that runs in steps and finishes on its own.