Agents — OScar Docs

01 — Structure

The agent.yaml format

Every agent is a single YAML file. The only required field is model. Everything else is optional.

model: claude-sonnet-4-5
system: |
  You are a senior software engineer.
  Keep answers concise and prefer code over explanation.
tools:
  - shell
  - filesystem
  - mcp

Full reference: docs.docker.com/ai/cagent covers every YAML key, provider config, and tool option.

02 — Models

Choosing a model

Set the model field to any model ID supported by your provider. OScar passes it directly to cagent without modification.

Provider	Example model ID	Env var required
Anthropic	claude-sonnet-4-5	ANTHROPIC_API_KEY
Anthropic	claude-opus-4-6	ANTHROPIC_API_KEY
OpenAI	gpt-4o	OPENAI_API_KEY
Google	gemini-2.0-flash	GOOGLE_API_KEY

The model identifier must exactly match the provider's API name. Check your provider's docs for the current list.

03 — Tools

Available tool sets

Tools grant the agent capabilities beyond text generation. List only the tools your use case requires — fewer tools means a tighter, more predictable agent.

Tool	What it can do
shell	Execute arbitrary shell commands in the working directory
filesystem	Read, write, and list files. Scoped to the session working dir by default
docker	Build and run Docker containers, inspect images and volumes
mcp	Connect to any Model Context Protocol server (databases, APIs, custom tools)
browser	Fetch and parse web pages

Sandbox tip: Use the -box suffix variants in OScar's agent picker (Cagent-box, Claude-box…) to run tools inside a Docker sandbox. See the Sandboxes page.

04 — System prompt

Giving the agent a persona

The optional system field is a freeform string sent as the system message before every conversation. Use it to set a role, constrain behaviour, or inject context.

system: |
  You are an expert in macOS development using Swift and SwiftUI.
  Always prefer AppKit for window management.
  When writing code, add only the minimal comments needed.

Keep system prompts focused. Overly long prompts consume tokens on every request and can confuse the model.

05 — Multiple agents

Organising several YAML files

Store your agent YAMLs in a folder and point OScar at it in Settings → General → Agents Folder. OScar discovers all .yaml / .yml files and lists them in the Quick Entry picker.

~/.config/oscar/agents/
  coding.yaml        # shell + filesystem, claude-sonnet
  research.yaml      # browser, gemini-flash
  docker-ops.yaml    # docker + shell, gpt-4o

Switch agents per conversation — the selection is remembered per session so each chat continues with the right agent.