Agent Profiles

What is a Profile?

A Profile is the blueprint for an agent. It captures:

Which LLM runtime and model to use
What the agent’s persona and instructions are (system prompt)
Which tools the agent is allowed to call
Which external MCP servers the agent can access

Profiles are reusable templates: one profile can back many concurrent sessions. Editing a profile never affects sessions that are already running.

The API and this concepts page use the term Profile. The dashboard and the orca CLI surface the same object as an Agent (dashboard routes /agents, /agents/new, /agents/:name/edit; CLI command group orca agents). The underlying schema and the /api/profiles/* endpoints are unchanged.

Profile Schema

type AgentProfile struct {
  ID           string        // auto-generated "agent-<uuid>"
  Name         string        // unique, human-readable label
  Runtime      string        // "pi" | "marlin" | "claude" | "codex" | "vercel"
  SystemPrompt string        // instructions injected as the system message
  Skills       []string      // explicit skill names injected into runs
  Tools        []string      // tool selectors (empty = default safe toolkit)
  MCPServers   []MCPServerSpec
  Model        string        // e.g. "claude-sonnet-4-6", "anthropic:claude-haiku-4-5"
  FS           *FSPolicy     // optional extra filesystem grants/denies
  WorkerMode      string               // "static" (default) | "sandbox"
  WorkerSubstrate string               // "e2b" | "daytona" | "docker" | "process"
  WorkerImage     string               // optional substrate-specific image override
  WorkerPlacement *WorkerPlacementInfo // computed on read; ignored on write
}

Creating a Profile

Most operators create and edit profiles in the dashboard. The API and generated SDKs use the same schema for automation, tenant onboarding, and tests.

curl -X POST https://api.orcapods.ai/api/profiles \
  -H "Authorization: Bearer $ORCA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "researcher",
    "runtime": "vercel",
    "model": "anthropic:claude-sonnet-4-6",
    "systemPrompt": "You are a research assistant. Always cite sources. Be concise.",
    "tools": ["web_search", "web_extract", "time_now"]
  }'

{
  "id": "agent-4f8a2e1b",
  "name": "researcher",
  "runtime": "vercel",
  "model": "anthropic:claude-sonnet-4-6",
  "systemPrompt": "You are a research assistant. Always cite sources. Be concise.",
  "tools": ["web_search", "web_extract", "time_now"],
  "mcpServers": [],
  "pinned": false,
  "readiness": { "ready": true, "items": [] }
}

Runtime Selection

The runtime field determines which agent-worker mode handles runs for this profile.

Runtime	SDK	Model format
`pi`	pi.dev coding agent SDK	`<provider>:<modelId>`, where `provider` is typically one of `runner_info.providers.pi`
`claude`	`@anthropic-ai/claude-agent-sdk`	`claude-sonnet-4-6`, `claude-haiku-4-5`
`codex`	`@openai/codex-sdk`	`codex-mini`, `o4-mini`
`vercel`	Vercel AI SDK	`anthropic:claude-`, `openai:gpt-`, `google:gemini-`, `groq:`
`marlin`	Orca Harness SDK	`openai:gpt-`, `anthropic:claude-`, `openrouter:<vendor>/<modelId>`

Use runtime: "vercel" when you want to switch providers without changing your runner infrastructure. Use runtime: "claude" when you need native Claude features like extended thinking or citations.

Marlin is outbound-only and therefore requires workerMode: "sandbox". Its model must be an explicit, priced openai:<modelId>, anthropic:<modelId>, or openrouter:<vendor>/<modelId>; there is no implicit runtime-default model because the profile model is also the billing identity. GET /api/models is the authoritative list of currently priced OpenRouter models; examples include openrouter:anthropic/claude-sonnet-4.5 and openrouter:anthropic/claude-haiku-4.5.

Worker Placement

workerMode selects how the runner reaches the agent-worker without changing the profile’s runtime or model behavior:

Value	Behavior
omitted or `"static"`	The runner calls the fixed sidecar URL configured for the runtime. This is the default for existing profiles.
`"sandbox"`	The runner uses one outbound-only worker per session. The worker communicates through an authenticated session-scoped connection.

Sandbox workers are launched lazily on the session’s first run, reused by later runs, and closed when the session shuts down. The runner must have WORKER_TOKEN_HMAC_KEY and a worker substrate configured, or an operator must launch the worker out of band. See Dynamic sandbox workers for runner configuration. For sandbox workers, workerSubstrate explicitly selects e2b, daytona, docker, or process. When omitted, Orca prefers the profile’s sandbox.provider if the runner serves it, then falls back to that runner’s default substrate. An explicit substrate that no runner serves is not rejected when the profile is saved; session placement fails with the fleet’s available substrates instead. workerImage overrides the runner’s image for the selected substrate: an E2B template id, Daytona snapshot name, or Docker image reference. Because those artifacts are not interchangeable, set workerSubstrate and workerImage together or leave both unset. On profile reads, a pooled Conductor may add workerPlacement with the resolved substrate, its source (explicit, shell, default, or unknown), whether it is servable, and explanatory requested or detail fields when needed. This value reflects the live fleet, is absent for static profiles, and is ignored rather than persisted when supplied on create or update.

{
  "name": "isolated-researcher",
  "runtime": "vercel",
  "workerMode": "sandbox",
  "workerSubstrate": "e2b",
  "model": "anthropic:claude-sonnet-4-6",
  "tools": ["@default"]
}

Tool Selectors

The tools array controls which platform tools the agent can invoke. Four forms are supported:

1. Named Tools

Include specific tools by name:

{
  "tools": ["web_search", "web_extract", "time_now", "runner_info"]
}

2. Capability Sentinels

Expand all tools in a capability group:

{
  "tools": ["@introspection", "@orchestration"]
}

Sentinel	Expands to
`@default`	Curated safe baseline: `@introspection`, `@fs`, `@pool`, `time_now`, `echo`, `math_add`
`@introspection`	State and utility tools such as `runner_info`, `profile_info`, `list_profiles`
`@fs`	File tools: `read_file`, `write_file`, `list_dir`, `delete_file`
`@pool`	Pod tools: `pool_info`, `pool_post`, `pool_inbox`
`@vfs`	VirtualFS shell/search tools: `vfs_execute`, `vfs_grep`
`@artifacts`	Raw run/session artifact tools
`@memory`	Per-profile Memory Bank: `memory_save`, `memory_recall`, `memory_list`, `memory_delete`. Selecting it also enables automatic prompt injection. See Memory Bank
`@orchestration`	Delegation and workflow run tools
`@profiles`	Profile admin: `create_profile`, `update_profile`, `delete_profile`, `attach_skill`, `detach_skill`.
`@pools.admin`	Pod admin: `create_pool`, `update_pool`, `delete_pool`, `add_pool_member`, `remove_pool_member`.
`@mcp`	MCP catalog admin: `add_mcp_server`, `update_mcp_server`, `delete_mcp_server`, `test_mcp_connection`. Secret values are never accepted inline; env/header inputs require a `secretRef` from the Secrets page.
`@skills`	Read-only skills catalog: `list_skills`, `describe_skill`.

3. Wildcard Patterns

Pattern-match tool names:

{
  "tools": ["web_*"]
}

This matches web_search and web_extract.

Empty = Defaults

{
  "tools": []
}

An omitted or empty array grants the curated default set (equivalent to ["@default"]).

Raw artifact tools (@artifacts), Memory Bank tools (@memory), and orchestration tools (@orchestration) are not in @default. Web tools currently sit under @introspection; without TAVILY_API_KEY, they return a tool-level “not configured” error.

Skills

The skills array names instruction bodies from the conductor skill store (see Skills). Profile create and update requests do not validate skills against the skill store: an unknown skill name is accepted and saved. A missing skill instead shows up as unreadiness on the profile’s readiness field, in the dashboard banner and Dependencies tab, and POST /api/runs refuses with profile_not_ready until the skill is installed. Use the dashboard picker or GET /api/skills to see what is available before attaching a skill. At run dispatch, the conductor resolves the named skills and sends the matched skill bodies, Agent Skills metadata, and resource manifests to the worker. Skills with executable scripts/ resources are marked requiresSandbox; their scripts execute through the runner’s run_skill_script tool inside the session sandbox. Tool capability selectors also auto-attach matching platform skills. For example, a profile with @vfs receives using-vfs, and an omitted or empty tools array receives the using-* skills for the @default bundle. In Postgres deployments, the conductor first reconciles the tenant’s platform-skill rows; a tenant-scoped tombstone keeps an intentionally deleted seed absent. Any auto-attached name that remains missing is skipped silently.

MCP Servers and Connected Apps

Profiles can attach inline external MCP servers or grant access to provider-managed connected apps (see MCP Integration). Inline servers are sent to the sidecar during a run:

{
  "name": "data-agent",
  "runtime": "vercel",
  "model": "anthropic:claude-sonnet-4-6",
  "systemPrompt": "You are a data analyst.",
  "tools": ["@introspection"],
  "mcpServers": [
    {
      "name": "company-db",
      "transport": "http",
      "url": "https://internal.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${INTERNAL_API_KEY}"
      }
    }
  ]
}

Header values prefixed with ${VAR} are resolved from the runner’s environment before the run envelope is sent to the sidecar. A header value can also be a whole-value secret://name reference, resolved instead from the tenant’s secrets manager. The two schemes are not mixed within one value. Unresolved secrets never reach the sidecar or appear in logs.

Connected apps use credential-free catalog references instead:

{
  "mcpServers": [
    {
      "name": "composio-gmail",
      "ref": "catalog://composio-gmail"
    }
  ]
}

Managed references authorize search_connected_app_tools and call_connected_app_tool. They are omitted from the worker’s native MCP transport configuration, and must not include transport, url, or headers.

MCP Server Spec

Field	Type	Description
`name`	string	Identifier (cannot be `"runner"`, reserved)
`transport`	`"http"` or `"sse"`	Required for inline servers
`url`	string	Required HTTP(S) URL for inline servers
`headers`	map[string]string	Optional inline-server headers (supports `${VAR}` placeholders or a whole-value `secret://name` reference)
`ref`	string	Managed reference in the exact form `catalog://<name>`; mutually exclusive with URL and headers

Filesystem Policy

Every profile gets an implicit home directory at /agents/{self}/** with read/write/delete access. The optional fs field adds more grants or denies:

{
  "fs": {
    "read": ["/datasets/**"],
    "write": ["/shared/{self}/**"],
    "delete": ["/shared/{self}/tmp/**"],
    "deny": ["/datasets/private/**"],
    "allow_mounts": ["/datasets", "/shared"]
  }
}

delete defaults to write when omitted. deny is a hard override. Pod membership can add more access under /pools/{pool}/...; see Pods. When the runtime has a per-session VirtualFS manager, session creation also allocates a VirtualFS session. fs.allow_mounts is the explicit mount-prefix allowlist for that lease. If it is omitted, Orca derives the allowlist from the first path segment of the profile’s read, write, and delete globs. If no mount prefixes can be derived, the VFS lease is unrestricted. In the dashboard profile editor’s Files & permissions section, setting the Mount allowlist field (fs.allow_mounts) does not add the @vfs tool selector automatically. Whether you set fs.allow_mounts through the dashboard or the API, add @vfs to tools yourself when the agent needs vfs_execute or vfs_grep.

Default Seed Profile

Every workspace gets a built-in sonar profile, pinned by default:

{
  "name": "sonar",
  "runtime": "marlin",
  "workerMode": "sandbox",
  "model": "openrouter:openai/gpt-5.6-luna",
  "tools": ["web_search", "web_extract", "time_now"],
  "skills": ["sonar-guide"]
}

This is the platform’s built-in helper agent: it answers questions about Orca itself using the docs site, and cannot be edited or deleted through the API. POST /api/orca/seed re-registers it idempotently if it is ever missing from a workspace.

Managing Profiles via API

Method	Path	Description
`GET`	`/api/profiles`	List all profiles
`GET`	`/api/profiles/{name}`	Get one profile
`POST`	`/api/profiles`	Create a new profile
`PUT`	`/api/profiles/{name}`	Update an existing profile
`DELETE`	`/api/profiles/{name}`	Delete a profile

Deleting a profile does not terminate existing sessions. Sessions hold a snapshot of their profile at creation time.

Profile Examples

Code Review Agent

{
  "name": "code-reviewer",
  "runtime": "claude",
  "model": "claude-sonnet-4-6",
  "systemPrompt": "You are an expert code reviewer. Focus on correctness, security, and maintainability. Provide specific, actionable feedback.",
  "tools": ["time_now", "session_info"]
}

Research Coordinator (with delegation)

{
  "name": "research-coordinator",
  "runtime": "vercel",
  "model": "anthropic:claude-sonnet-4-6",
  "systemPrompt": "You coordinate research tasks by delegating sub-tasks to specialist agents and synthesizing their results.",
  "tools": ["@default", "@orchestration", "web_search"]
}

Set AGENT_ORC_ORCHESTRATION_TOOLS=off on the runner to remove orchestration tools entirely in restricted environments.

Data Pipeline Agent (with external MCP)

{
  "name": "data-engineer",
  "runtime": "vercel",
  "model": "openai:gpt-5.2",
  "systemPrompt": "You build and manage data pipelines. Use the database tools to query and transform data.",
  "tools": ["time_now"],
  "mcpServers": [
    {
      "name": "warehouse",
      "transport": "http",
      "url": "https://warehouse.internal/mcp",
      "headers": { "X-API-Key": "${WAREHOUSE_API_KEY}" }
    }
  ]
}

Get Started

Core Concepts

Guides

Runbooks

Agent Profiles

What is a Profile?

Profile Schema

Creating a Profile

Runtime Selection

Worker Placement

Tool Selectors

1. Named Tools

2. Capability Sentinels

3. Wildcard Patterns

Empty = Defaults

Skills

MCP Servers and Connected Apps

MCP Server Spec

Filesystem Policy

Default Seed Profile

Managing Profiles via API

Profile Examples

​What is a Profile?

​Profile Schema

​Creating a Profile

​Runtime Selection

​Worker Placement

​Tool Selectors

​1. Named Tools

​2. Capability Sentinels

​3. Wildcard Patterns

​Empty = Defaults

​Skills

​MCP Servers and Connected Apps

​MCP Server Spec

​Filesystem Policy

​Default Seed Profile

​Managing Profiles via API

​Profile Examples

What is a Profile?

Profile Schema

Creating a Profile

Runtime Selection

Worker Placement

Tool Selectors

1. Named Tools

2. Capability Sentinels

3. Wildcard Patterns

Empty = Defaults

Skills

MCP Servers and Connected Apps

MCP Server Spec

Filesystem Policy

Default Seed Profile

Managing Profiles via API

Profile Examples