OUouterport
Agent Personas

Create agent persona

Changed on

Create a new agent persona for the current user.

post/api/v0/agent/personas

Request

Request body

namestring required

The name of the persona.

descriptionstring

The description of the persona.

promptstring

The system prompt for the persona.

builtin_tool_idsstring[]

Built-in tool IDs to assign to this persona.

builtin_tool_configsobject

Per-builtin config, keyed by builtin tool id. Each entry is validated against the Pydantic schema registered for that tool in op_core.builtin_tool_configs. Only configurable builtins (e.g. invoke_persona) accept a config; others must be omitted.

knowledge_graph_idstring uuid nullable

The graph-enabled collection the persona's knowledge-graph tools target. Kept only when builtin_tool_ids enables such a tool, and then attached as one of the persona's knowledge bases. Omitted, the graph a knowledge-graph tool's builtin_tool_configs entry names is used.

custom_tool_idsstring[]

Custom tool UUIDs to assign to this persona.

mcp_server_idsstring[]

MCP server UUIDs to connect. Every tool each server exposes joins this persona's toolset, discovered when a run starts.

knowledge_base_idsstring[]

Knowledge base UUIDs to assign to this persona.

skill_idsstring[]

Skill UUIDs to preload: instruction documents the agent can read on demand via the read_skill tool.

Response

Successful Response

idstring uuid required

The ID of the persona.

namestring required

The name of the persona.

descriptionstring required

The description of the persona.

promptstring required

The system prompt for the persona.

builtin_tool_idsstring[]

Built-in tool IDs assigned to this persona.

builtin_tool_configsobject

Per-builtin config keyed by tool id. Only configurable builtins (currently invoke_persona) carry config; the dict is sparse.

knowledge_graph_idstring uuid nullable

The graph-enabled collection the persona's knowledge-graph tools target; null when none is wired, no such tool is enabled, or the collection was deleted.

is_roamingboolean

True iff the persona enables a tool that requires a workspace.

custom_tool_idsstring[]

Custom tool UUIDs assigned to this persona.

knowledge_base_idsstring[]

Knowledge base UUIDs assigned to this persona.

skill_idsstring[]

Skill UUIDs preloaded by this persona: instruction documents the agent can read on demand via the read_skill tool.

mcp_server_idsstring[]

MCP server UUIDs connected to this persona.

created_atstring date-time required

When the persona was created.

updated_atstring date-time required

When the persona was last updated.

Changes

  • ecd5b922e78aRevision changes
    • info

      added the new optional request property

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

  • fd2664afd5a3Revision changes
    • info

      added the optional property to the response with the status