Agents

A Stackbone agent is an in-process deep agent, not a subprocess with its own port. You author it as one file: a model, a system prompt, and the tools it can call. The runtime builds it once at boot and serves it over the standard OpenAI, Anthropic and AG-UI chat APIs, so any chat client, or any AG-UI frontend, can talk to it with nothing more than a base URL and a key.

Agents are built on LangChain's deep-agent framework. Stackbone wraps it with a default model bridge, your org's injected model key, and a durable filesystem backed by your workspace's own storage, so you focus on the agent itself.

The model in one minute

• Authored as one file. An agent is deep-agents/<name>/index.ts, which default-exports defineDeepAgent({ model, systemPrompt, tools }) from @stackbone/sdk/deep. There is no server to hand-roll and no per-agent manifest.
• Discovered by convention. Any folder under deep-agents/ that has an index.ts is an agent. Drop one in and stackbone dev picks it up. The folder name is also the agent's identity: it is the model value a chat client sends to talk to it.
• Spoken over a standard wire. A request's model field picks which agent answers, on the same POST /openai/v1/chat/completions and POST /anthropic/v1/messages endpoints every agent in the workspace shares. There is no proprietary session protocol to learn. An AG-UI client reaches the same agent at POST /agui/v1/agents/:name, with interrupts, frontend tools and shared state on top. See Agent protocol for the full contract.
• Tools are plain LangChain. Each tool is a function wrapped with tool(...) from @langchain/core/tools, given a name, a description, and a Zod schema. The model decides when to call it from those three things.
• One ambient client. Inside a tool's handler you reach the platform through the shared stackbone handle (stackbone.config, .storage, .rag, .database, and more). No constructor, no credential wiring.

// A deep agent is one file: deep-agents/<name>/index.ts.
import { tool } from '@langchain/core/tools';
import { z } from 'zod';
import { defineDeepAgent } from '@stackbone/sdk/deep';
import { stackbone } from '@stackbone/sdk';

const getGreeting = tool(
  async () => {
    const greeting = await stackbone.config.get('greeting');
    return greeting.error ? 'Hello!' : String(greeting.data);
  },
  {
    name: 'get_greeting',
    description: 'Look up the configured greeting.',
    schema: z.object({}),
  },
);

export default defineDeepAgent({
  model: 'openai/gpt-4o-mini',
  systemPrompt: 'You are a friendly assistant. Use get_greeting to say hello.',
  tools: [getGreeting],
});

Where to go next

• Getting started: scaffold, write, and run your first agent.
• Examples: complete agents you can copy.
• Workflow agents: combine an agent with a durable workflow.
• Agent protocol: the full HTTP contract, the session key, tool approvals, and the AG-UI surface.