How do you build Plugsky AI agents with memory, tools and orchestration?

Key facts

Agent endpoint	POST https://api.plugsky.com/v1/chat/completions with tools and tool_choice
Memory	Message history for short-term context; POST /v1/embeddings with plugsky-embed for long-term recall
Orchestration	Mix model aliases: plugsky-micro for cheap steps, plugsky-pro for reasoning, plugsky-frontier for hard tasks
Model fusion	plugsky-fusion runs a configured chain; check the docs for routing endpoint status
Tools	OpenAI-style function calling is live on supported models
Agents in the box	The Plugsky CLI ships an agent loop with file editing, a shell sandbox, MCP and RAG indexing
Roadmap	Assistants and responses endpoints are coming soon; build on chat completions today
Governance	Scoped keys, audit logs, region pinning and usage analytics for production agents

TL;DR

• The agent loop is chat completions plus tool results.
• Store memory yourself: messages short-term, embeddings long-term.
• Pick a model per step instead of one model for everything.
• Cap iterations and allowlist tools before production.
• Assistants-style APIs are coming soon; chat completions is ready now.

How it works, step by step

1. Create a scoped API key for the agent and set a per-request timeout.
2. Define tools as JSON schemas with clear names and parameter descriptions.
3. Run the loop: call the model, execute tool_calls, append tool messages, repeat.
4. Stop on a final answer or a maximum iteration count.
5. Add long-term memory by embedding facts with plugsky-embed and retrieving them by similarity.
6. Choose models per step — cheap for extraction, stronger for planning.
7. Add allowlists, human approval and audit logging before production.

Try it yourself

Open the AI agent builder →

The agent loop on chat completions

An agent is a loop around chat completions with a tools array: the model picks a function, your code executes it, and the result goes back into the conversation:

import json
from openai import OpenAI

client = OpenAI(api_key="sk-live-…", base_url="https://api.plugsky.com/v1")

tools = [{
    "type": "function",
    "function": {
        "name": "search_docs",
        "description": "Search internal documentation",
        "parameters": {
            "type": "object",
            "properties": {"query": {"type": "string"}},
            "required": ["query"],
        },
    },
}]

messages = [
    {"role": "system", "content": "Use search_docs before answering. Be concise."},
    {"role": "user", "content": "How do I rotate an API key?"},
]

for _ in range(6):
    resp = client.chat.completions.create(
        model="plugsky-pro", messages=messages, tools=tools, tool_choice="auto")
    msg = resp.choices[0].message
    messages.append(msg)
    if not msg.tool_calls:
        print(msg.content)
        break
    for call in msg.tool_calls:
        result = run_tool(call.function.name, json.loads(call.function.arguments))
        messages.append({
            "role": "tool",
            "tool_call_id": call.id,
            "content": json.dumps(result),
        })

Cap the loop — an unbounded agent burns quota and wall-clock time.

Memory: history and embeddings

Short-term memory is the message list — trim it by token count, keeping the system prompt and the most recent turns. When the history exceeds the context window, summarize older turns with a cheap model.

Long-term memory is retrieval. Embed facts, documents and past resolutions with plugsky-embed, store the vectors with their metadata, and fetch the nearest neighbours for the current query before each turn:

emb = client.embeddings.create(
    model="plugsky-embed",
    input=[user_question],
).data[0].embedding

Inject the top matches into the system or context message. Store what actually helped, not every session message.

Orchestration patterns

Four patterns cover most agents:

• Single agent with tools: one loop, one model, a small toolset. Start here.
• Planner and executor: a strong model decomposes the task; a cheaper model executes each step.
• Router: classify the request, then send it to the agent or chain that owns it — often cheaper than one general prompt.
• Critic loop: one model drafts, another reviews against explicit criteria, with a bounded number of revisions.

Model choice is part of orchestration. Use plugsky-micro or plugsky-lite for classification and extraction, plugsky-pro for planning and synthesis, and plugsky-frontier for the hardest reasoning. plugsky-fusion runs a configured chain; check the docs for the routing endpoint status.

Guardrails for production agents

Agents take actions, so the minimum safety set is:

• Allowlist tools per agent role and validate every argument before execution.
• Cap iterations and spend per request and per user.
• Require human approval for writes to external systems, payments or anything irreversible.
• Use scoped keys with the narrowest permissions, one per agent fleet, rotated on schedule.
• Log everything: model, prompt, tool call, result and token usage per turn.
• Pin regions where residency matters and record which model answered each request.

Plugsky's audit logs, scoped keys and usage analytics cover the platform side; the rest is application discipline. Assistants and responses endpoints are coming soon, so keep agent state in your own database — that also keeps it portable.

Honest comparison

Capability	Plugsky chat + tools	Assistants-style APIs	Framework agents (LangChain/AutoGen)
Build model	Tool loop on chat completions	Managed threads and runs	Framework abstractions
Memory	You own history; embeddings for recall	Provider stores threads	Framework stores it
Model choice	30+ models, mix per role	Vendor models	Whatever you wire up
Control	Full control of prompts and loop	Less control, faster start	Framework-dependent
Governance	Scoped keys, audit logs, region pinning	Vendor controls	Your responsibility
Status today	Live	Coming soon on Plugsky	Live with the Plugsky endpoint

Frequently asked questions

What is a Plugsky agent, concretely?

It is a loop around /v1/chat/completions with a tools array: the model requests a tool, your code runs it, the result is appended and the loop repeats until the model answers.

Does Plugsky have an Assistants API?

Not yet — assistants and the responses endpoint are coming soon. Build agents on chat completions with function calling today.

How do I give an agent memory?

Keep the message history for short-term context and embed durable facts with plugsky-embed for long-term recall in your own vector store.

Which model should an agent use?

Match the model to the step: plugsky-micro for cheap classification, plugsky-lite for routine turns, plugsky-pro for planning and plugsky-frontier for hard reasoning.

How do I stop runaway loops?

Cap iterations and spend per request, trim history by tokens, and require human approval for irreversible actions.

Can agents call my internal APIs?

Yes. Define tools with JSON schemas, validate arguments server-side, and return structured results. Never expose a tool that can execute arbitrary code or SQL.

Does Plugsky ship an agent loop?

Yes. The Plugsky CLI includes an agent loop with file editing, a shell sandbox, MCP support and RAG indexing, and the docs cover its approval modes.

How do I audit agent actions?

Log model, prompt, tool calls and results per turn, and use Plugsky's scoped keys and audit logs. Region pinning keeps the data path auditable.