How do you build API orchestration with AI agents?

Key facts

Endpoint	POST /v1/chat/completions with tools and tool_choice; function calling is live
Tool schemas	JSON Schema definitions; validate every argument server-side before execution
Models	30+ models; use plugsky-micro for dispatch and plugsky-pro for multi-step planning
Parallel calls	Execute independent tool calls concurrently when the model returns several per turn
Pricing model	Flat monthly self-serve plans with unlimited fair-use usage
Governance	Scoped keys with least privilege, audit logs and usage analytics
Deployment	Plugsky cloud, VPC, on-prem and air-gapped options
Roadmap	Assistants and responses endpoints are coming soon; orchestrate on chat completions today

TL;DR

• Expose a small, well-named tool registry instead of every internal endpoint.
• Separate read tools from write tools and gate writes behind approval.
• Make every write idempotent with a caller-supplied key.
• Bound the loop by iterations, wall-clock time and spend.
• Evaluate tool-call precision and task success, not just final prose.

How it works, step by step

1. Map the workflow and mark which steps are deterministic and which need judgment.
2. Select the smallest tool set that covers the workflow; write JSON schemas with typed parameters and strict enums.
3. Split tools into read and write classes, and require explicit approval for writes and irreversible actions.
4. Implement the loop: plan, validate arguments, execute, append results, repeat until done or a cap is hit.
5. Add idempotency keys, timeouts, backoff and compensation for partially completed workflows.
6. Log every call and evaluate tool-call precision and end-to-end task success on a test suite.

Try it yourself

Open the tool registry builder →

When an agent is the right orchestrator

An agent earns its place when the path through your APIs is not known in advance: ticket triage that may need three different systems, onboarding flows that branch on data quality, or support actions that depend on what the customer already has.

If the sequence is fixed, use a workflow engine and call models only for the judgment steps. A deterministic pipeline is cheaper, faster and easier to audit than an agent that rediscovers the same order every time. The practical test: if you can draw the flowchart with no branches that depend on unstructured content, you do not need an agent.

Designing the tool registry

The registry is the contract between the model and your systems:

• Names: verb-first and specific — get_invoice_status, not invoices.
• Schemas: typed parameters, enums for closed sets, required fields marked, and no free-form strings where an id will do.
• Descriptions: one sentence on what the tool does and one on when not to use it.
• Errors: return structured errors with codes the model can act on; never leak stack traces.
• Class: tag tools as read or write so approval rules and rate limits attach automatically.
• Scope: start with three to eight tools. Larger registries increase wrong-tool selection more than they increase capability.

Implementation: plan, validate, execute

The executor is ordinary application code with the model in the planning seat:

1. Send the request with the registry and a system prompt that names the goal and the approval rules.
2. Receive tool calls; validate every argument against the schema and the caller's permissions.
3. Execute reads immediately; queue writes for approval or run them idempotently with a caller-supplied key.
4. Append structured results to the conversation and repeat until the model answers or the iteration cap is reached.
5. On failure, return the error to the model once; if it repeats, stop and surface a human-readable summary.

Run independent calls concurrently, but never parallelize writes that touch the same record.

Evaluation and operations

Score orchestration at two levels:

• Tool-call precision: share of calls that were necessary and correctly parameterized, measured against a labeled workflow set.
• Task success: end-to-end completion rate, including correct handling of partial failures.
• Safety: number of unapproved writes, duplicate writes and out-of-scope calls. This must be zero, not low.
• Recovery: how often the agent recovers from an API error without human help.

Replay failed traces after every prompt or registry change. Keep a kill switch per tool class so a misbehaving agent loses write access without taking down reads.

Limitations

Agents orchestrate well but guarantee nothing. Honest constraints to design around:

• The model cannot know a tool's semantics beyond its schema, so ambiguous descriptions cause real side effects. Treat schemas as production contracts with owners.
• Long workflows accumulate context; compaction can drop details the model needed, so persist workflow state in your database, not the transcript.
• Assistants and responses endpoints are coming soon, so agent state management stays your responsibility today.
• Latency compounds with each model round trip; keep human-facing flows thin and move bulk work to asynchronous queues.

Honest comparison

Capability	Agent orchestration on Plugsky	Workflow engine only	Hand-written integration code
Branching on unstructured input	Model plans from tool results	Hard-coded rules	Manual code paths
Tool definitions	Typed JSON schemas with read/write classes	Not applicable	Internal functions
Approval gates	Attached per tool class	Custom	Custom
Model choice	30+ models, mix per step	None or one model	Whatever you wire
Auditability	Per-call logs plus platform audit logs	Workflow logs	Application logs only

Frequently asked questions

What is API orchestration with AI agents?

It is an agent loop where internal APIs are exposed as typed tools and the model decides the sequence of calls, while your code validates arguments, enforces permissions and executes requests.

How many tools should an agent have?

Start with three to eight that cover the workflow. Wrong-tool selection grows faster than capability as the registry expands.

Does Plugsky support parallel tool calls?

Supported models can return multiple tool calls in one turn. Execute independent reads concurrently, and serialize writes that affect the same record.

How do I keep writes safe?

Split read and write tools, require explicit approval or idempotency keys for writes, cap iterations, and keep a kill switch that revokes write access.

Where should workflow state live?

In your own database. Keep the transcript for reasoning, but persist durable state so compaction or a restart cannot lose progress.

Is there an Assistants API to manage this?

Not yet — assistants and responses endpoints are coming soon. Today you orchestrate on chat completions with function calling and own the state.

Can I prototype on the free plan?

Yes. plugsky-micro and plugsky-lite are free with no card, and a 14-day full-access trial unlocks stronger models for planning-heavy workflows.