How Agent Studio works
Understand how skills, graphs, tools, executions, approvals, and organizations fit together.
Use this model to decide what to create, where to scope it, and what to inspect when a run does not behave as expected. Agent Studio separates reusable behavior, orchestration, external capabilities, runtime records, human decisions, and tenancy so that you can change one concern without treating the whole workflow as a single object.
Resource model
An organization can scope shared skills, executions, MCP servers, vault entries, triggers, audit records, and policies. A skill contains the reusable contract for an agent capability: instructions, schemas, permitted tools, approval behavior, and execution limits. A skill version identifies the revision that an execution runs. An agent graph supplies explicit control flow when the capability needs multiple nodes, tools, routes, loops, or approval points.
Tools provide capabilities to a workflow. They can be built into Agent Studio or supplied through integrations such as MCP and OpenAPI. Permitting a tool on a skill is a boundary: the execution may select only from the tools available to that definition and version.
An execution is the persisted record of a run. It carries status, input and output, and the planner, node, and tool activity needed to inspect what happened. An approval request is a human decision gate associated with a run; when a configured action requires review, the execution pauses until that request is resolved.
Choose the right resource
Use this comparison when you plan a workflow.
| Resource | Use it for | Observable consequence |
|---|---|---|
| Skill | A reusable, bounded capability | The detail page shows instructions, schemas, tools, limits, and versions. |
| Skill version | A specific revision of a skill | An execution identifies which revision it ran; a draft can change while a published revision is fixed. |
| Agent graph | Explicit multi-step control flow | The canvas shows typed nodes and directed edges from START to END. |
| Tool | Retrieval or an external action | The execution trace records permission checks and tool selection. |
| Execution | One run of a skill version | Status, inputs, outputs, steps, logs, and tool calls remain available for inspection. |
| Approval request | A human gate before a protected action | The run enters a paused state until a reviewer responds. |
| Organization | A shared tenant boundary | Membership and permissions apply to organization-scoped resources. |
Graph invariants
Agent Studio accepts version-1 directed graphs. Every graph must contain at least one node, include both a start node and an end node, and use edges whose source and target refer to node IDs that exist in the same definition.
The supported graph vocabulary includes agents and supervisors, explicit tools, routers, approvals, bounded loops, parallel branches, subgraphs, MCP servers and tools, skills, HTTP calls, transformations, delays, aggregation, variables, outputs, notes, and frames. These types serve different purposes: operational nodes affect execution, while notes and frames help organize the canvas.
Use a skill without a custom graph when one set of instructions, schemas, tools, and limits is enough. Add an agent graph when the order of work, branching, parallelism, or a human checkpoint must be explicit.
Scope and ownership
Personal skills and executions belong to the signed-in user. Organization-scoped work belongs within an organization that has members and roles. Creating an organization-scoped skill requires membership and the relevant creation permission; starting an organization execution requires membership and execution permission.
Choose the scope before others begin using the workflow. Moving from personal experimentation to shared operation changes who can discover, edit, execute, and administer the associated resources. An organization also groups operational dependencies such as MCP servers, vault entries, and schedules, so administrators can govern them within the same tenant boundary.
Execution and approval lifecycle
An execution begins from a skill version and supplied input. Agent Studio validates access and the input contract, plans the work, checks tool permissions, and records node and tool activity. The run then reaches a terminal status such as completed or failed, or pauses when an approval gate requires a human decision.
An approval gate is meaningful only for an action that must not proceed autonomously. Read the trace and the pending request together: the trace explains where the run paused, while the request captures the decision needed to continue or stop it.