A plain greeter

The smallest useful agent is a name and a model, with no tools attached. That makes the prompt the whole contract: it is the only thing deciding how the agent answers, and it lives in the catalogue rather than in the file. This one welcomes a person by name and stops at two sentences.

The whole agent is a single deep-agents/greeter/index.ts file. Drop it into a workspace laid out the way Getting started with agents describes, then run it with stackbone dev.

deep-agents/greeter/index.ts

import { defineDeepAgent } from '@stackbone/sdk/deep';

export default defineDeepAgent({
  name: 'greeter',
  model: 'openai/gpt-4o-mini',
});

The voice lives in the prompt catalogue, not in the file. In Studio, open this agent and write the prompt keyed greeter, then publish it:

You are a warm, concise greeter.
Welcome the person by name when they give it, and offer one helpful next step.
Keep every reply to two sentences.

Run stackbone dev, then:

curl http://127.0.0.1:4242/openai/v1/chat/completions \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer local-dev' \
  -d '{"model":"greeter","messages":[{"role":"user","content":"Hi, I am Sam"}]}'

You pick the agent with the request's model field, which matches the folder name. greeter reaches this file.

What's next

A config-driven agent: move the tone out of the prompt so an operator can change it without republishing it.
A retrieval-backed support agent: give the agent tools that search a knowledge base and read a database.
What is an agent: the model behind this example.