How does the Plugsky AI agents API work?

Key facts

Endpoint	POST /v1/agents/{agent_id}/agent/runs
Run steps	Default 10, configurable via max_steps; max 50 self-serve, 200 Enterprise
Tools	Named tools via OpenAI-format function calling
Memory	Conversation, tool logs and structured memory namespaced per agent; vector memory via RAG
Streaming	Set stream: true for SSE step events
Approval gates	requires_approval on sensitive tools pauses the run for human review
Multi-agent	Named sub-agents with shared memory in Agent Cloud
Product status	Live

TL;DR

• Agents run as API calls: send a goal plus tools, get steps, tool calls and output.
• max_steps defaults to 10, configurable up to 50 self-serve and 200 on Enterprise.
• Memory and tool logs are namespaced per agent; RAG adds vector memory.
• Streaming returns each planning and tool step over SSE as it happens.
• requires_approval pauses sensitive tool calls for a human decision.

How it works, step by step

1. Create an agent (or use an existing agent_id) in your workspace.
2. Define the tools the agent may call, using OpenAI-format function schemas.
3. POST a goal to /v1/agents/{agent_id}/agent/runs with tools and max_steps.
4. Set stream: true if you want step-by-step SSE events while the run executes.
5. Add requires_approval to destructive or high-cost tools before production use.
6. Inspect the returned steps array, then log the run id for audit and replay.

Try it yourself

Open the function-calling schema generator →

How an agent run works

An agent run is a single API call that may take several model turns. You send an input, the tools the agent is allowed to use and a step budget; the service plans, chooses tools, executes them and returns a final output. Every run returns a steps array that records each thought and tool call, so you can replay exactly what happened.

Runs are capped by max_steps: the default is 10, with a maximum of 50 on self-serve plans and 200 on Enterprise. When an agent needs more moves than one request should reasonably contain, break the workflow into sub-agents instead of raising the limit.

Tools, memory and guardrails

Tools use the same function-calling shape as chat completions, so existing schemas port directly. Memory is namespaced per agent: conversation history, tool-call logs and structured state stay isolated, and vector memory can be backed by the RAG API when an agent needs to retrieve from documents.

• Set requires_approval: true on any tool that writes, sends or spends.
• Keep tool descriptions narrow — the model chooses tools from their descriptions.
• Prefer several small tools over one tool with a mode switch.

Streaming and observability

Set stream: true to receive SSE events as the run progresses. Each event carries the step type, content and any tool result, which lets a UI show the agent thinking in real time instead of waiting for the final answer. Because every run is also logged with model, latency and token counts, you can ship the stream to users and keep the full trace for audits.

When to use agents instead of chat completions

Use chat completions for single-shot generation, extraction and classification. Use the agents API when a task needs multiple dependent tool calls, retries or a record of intermediate reasoning. If you need the OpenAI Assistants-style stateful threads with built-in file search, note that the Assistants-compatible endpoint is listed as coming soon in the docs — the agent runs API above is the supported production path today.

Honest comparison

Capability	Plugsky agents API	Chat completions only	DIY agent framework
Multi-step execution	Built into a single run with step trace	You orchestrate every turn	You build the loop
Tool calls	OpenAI-format tools, executed and logged	Model returns calls, you execute	You build the runtime
Memory	Namespaced per agent, optional vector memory	You resend history	You build storage
Human approval	requires_approval gate per tool	Manual	Custom
Streaming	SSE step events	SSE deltas	Custom
Ops overhead	Managed endpoint and logs	Low but manual	High — one more system to run