Agent Profiles

Reusable agent templates that define how an agent thinks, which tools it can use, and which LLM it runs on.

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.

---

Profile Schema

type AgentProfile struct {
  ID           string        // auto-generated "agent-<uuid>"
  Name         string        // unique, human-readable label
  Runtime      string        // "claude" | "codex" | "general"
  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

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

---

Runtime Selection

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

Runtime	SDK	Model format
claude	@anthropic-ai/claude-agent-sdk	claude-sonnet-4-6, claude-haiku-4-5
codex	@openai/codex-sdk	codex-mini, o4-mini
general	Vercel AI SDK	anthropic:claude-*, openai:gpt-*, google:gemini-*, groq:*

Use runtime: "general" 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.

---

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 calls the runner’s authenticated /worker/* routes; the runner does not dial into the sandbox.

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": "general",
  "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	Pool 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	Pool 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 reject confirmed unknown skill names with 400 Bad Request, so use the dashboard picker or GET /api/skills before attaching them. In Postgres-backed conductor deployments, validation uses the tenant-scoped skill store that backs the dashboard skill list. In local no-DB mode, validation falls back to the in-memory skill catalog; if no catalog is available, Orca skips validation so degraded local setups can still register profiles.

At run dispatch, the conductor resolves the validated names 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": "general",
  "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. 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)
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. Pool membership can add more access under /pools/{pool}/...; see Agent Pools.

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, enabling Limit to specific mounts under File access also adds the @vfs tool selector automatically so the profile receives vfs_execute and vfs_grep. API clients that set fs.allow_mounts directly should include @vfs in tools when the agent needs those VirtualFS tools.

---

Default Seed Profile

Every fresh deployment includes a general profile:

{
  "name": "general",
  "runtime": "general",
  "model": "anthropic:claude-haiku-4-5",
  "systemPrompt": "You are a general-purpose assistant. Keep answers concise and use tools when helpful.",
  "tools": ["@default", "web.*"]
}

This is what you see in the Workbench out of the box.

The seeded profile still carries the legacy web.* selector. The current web tool names are web_search and web_extract; @default selects them today because they carry the introspection capability. New explicit web selectors should use exact names or web_*.

---

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
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": "general",
  "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": "general",
  "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}" }
    }
  ]
}