Skip to content
OpenBot Docs

Your First Agent

In this tutorial you will add a custom agent under ~/.openbot/agents. Agents are YAML-fronted markdown files: the frontmatter chooses which plugins compose the agent (including the LLM runtime); the markdown body is the system instructions passed to that runtime.

If you are integrating via HTTP/SSE, skim Your First Channel first — channelId and threadId are both required for conversations, alongside agentId.

Prerequisites

Section titled “Prerequisites”

1. Pick an agent id

Section titled “1. Pick an agent id”

Each agent lives in its own folder under ~/.openbot/agents/. The folder name becomes the agent id (what clients and APIs use when they target an agent).

For example, use study-buddy:

Terminal window
mkdir -p ~/.openbot/agents/study-buddy

2. Create AGENT.md

Section titled “2. Create AGENT.md”

Inside that folder, create AGENT.md with YAML frontmatter and a markdown body. The body is your agent’s system prompt (agentDetails.instructions for the runtime).

Minimal pattern: include the ai-sdk runtime (it handles agent:invoke and drives the LLM loop), plus storage and ui so the agent can use persisted context and the client can render widgets.

---
name: Study Buddy
description: Explains topics clearly and checks your understanding.
plugins:
  - id: ai-sdk
    config:
      model: openai/gpt-4o-mini
  - id: storage
  - id: ui
---


You are a friendly tutor. Explain ideas in short sections, use plain language,
and end with a quick question so the user can confirm they understood.

Adjust model to any provider string your installation supports (see Built-in Plugins — ai-sdk).

3. Start the server

Section titled “3. Start the server”

Agents are loaded from disk when the server starts. After saving AGENT.md:

Terminal window
openbot start

If OpenBot was already running, restart it so the new agent is picked up.

4. Try it

Section titled “4. Try it”

With the server on the default port (http://localhost:4132), use your OpenBot client or the HTTP API to talk to the agent whose id matches the folder name (study-buddy in this example). Use POST /api/publish with correlation ids — see Your First Channel for channelId, threadId, and agentId.

How it works

Section titled “How it works”
  • Runtime plugin: At least one plugin must handle agent:invoke — typically ai-sdk. Without a runtime, the agent will not answer user messages.
  • plugins list: Order and composition matter: ai-sdk merges in tools from other plugins you list (for example storage, mcp). Specialized runtimes such as claude-code or gemini-cli bring their own tool loops; pairing separate tool plugins with those runtimes has no effect (see upstream agent notes).
  • Instructions: Everything below the closing --- of the frontmatter is the system prompt for the runtime.

Next steps

Section titled “Next steps”