Agent Example

AI agent API example: a cost-aware planner and executor

One expensive model for every step is the wrong architecture. This minimal example routes planning to a frontier model and execution to a cheap one, with a token budget and an OpenAI-compatible API.

Short answer. Use a frontier model to produce a short plan, run the plan with a cheap fast model, and stop when the token budget or step limit is reached. The pattern is model-agnostic: keep the base URL, model map and budget in configuration so 2027 model changes are a config edit.

The planner/executor pattern

Role Model tier Responsibility Budget rule
PlannerFrontier reasoningUnderstand the task, produce 3–5 steps, decide when to stopOne call per run; cap output at ~300 tokens
ExecutorCheap fast modelComplete one bounded step at a timeOne call per step; cap output and total tokens
GuardYour codeStop on budget, step count or repeated failureHard cap per run; log tokens and retries

The planner is not a chat agent with memory. It is a single structured call. The executor does the repetitive work. If a step fails twice, escalate it back to the planner or stop; do not loop forever.

The code

This is a complete minimal example. It uses the OpenAI Python SDK, two Plugsky model IDs and a token budget. Replace the API key with your own.

import json
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["PLUGSKY_API_KEY"],
    base_url="https://api.plugsky.com/v1",
)

PLANNER = "plugsky-ultra"
EXECUTOR = "plugsky-micro"
MAX_TOKENS = 40_000
used = 0


def ask(model: str, prompt: str, max_tokens: int = 600) -> str:
    global used
    if used >= MAX_TOKENS:
        raise RuntimeError("Token budget exhausted")

    response = client.chat.completions.create(
        model=model,
        messages=[{"role": "user", "content": prompt}],
        max_tokens=max_tokens,
        temperature=0.2,
    )
    used += getattr(response.usage, "total_tokens", 0) or 0
    return response.choices[0].message.content or ""


def plan(task: str) -> list[str]:
    prompt = (
        "Return a JSON array of 3 short steps for this task. "
        "No prose, no markdown. Task: " + task
    )
    raw = ask(PLANNER, prompt, max_tokens=300)
    try:
        steps = json.loads(raw)
        if isinstance(steps, list) and steps:
            return [str(step) for step in steps][:3]
    except json.JSONDecodeError:
        pass
    return [task]


def execute(step: str) -> str:
    return ask(
        EXECUTOR,
        "Complete this step in 3 concise bullet points: " + step,
        max_tokens=400,
    )


if __name__ == "__main__":
    task = "Plan a launch checklist for a free AI API tier"
    for index, step in enumerate(plan(task), start=1):
        print(f"\nStep {index}: {step}")
        print(execute(step))
    print(f"\nTokens used: {used}")

The code is intentionally small. It does not stream, retry or persist state. Those are production concerns, not pattern concerns.

Run it

  1. Install the SDK: pip install openai.
  2. Set the key: export PLUGSKY_API_KEY="sk-live-...".
  3. Save the code as agent.py and run python agent.py.
  4. Check the token count at the end. If it is close to the budget, lower MAX_TOKENS or shorten the executor prompt.

To use a local executor, change its client to http://localhost:11434/v1 with Ollama, or http://localhost:1234/v1 with LM Studio. The planner can stay hosted if policy allows.

What it costs

At 2026 GPT-OSS rates of $0.15 input and $0.60 output per million tokens and an 80/20 input-output mix, the blended rate is about $0.24 per million tokens. For a monthly agent volume:

Tokens/month Per-token estimate Flat plan Cheaper option
1M$0.24$8 HobbyPer-token
10M$2.40$8 HobbyPer-token
60M$14.40$8 HobbyHobby
120M$28.80$20 StarterStarter

These are arithmetic examples, not quotes. The planner tier may cost more per token than the executor; the routing is what keeps the blended bill down. Use the cost calculator with your own mix.

Adding tools

When a step needs a real action, add an OpenAI tools schema and execute the returned call in your code:

tools = [{
    "type": "function",
    "function": {
        "name": "lookup_order",
        "description": "Look up an order by ID.",
        "parameters": {
            "type": "object",
            "properties": {"order_id": {"type": "string"}},
            "required": ["order_id"],
        },
    },
}]

response = client.chat.completions.create(
    model=EXECUTOR,
    messages=[{"role": "user", "content": "Check order A-1042."}],
    tools=tools,
    tool_choice="auto",
)

Validate every argument before running a tool. Set a per-run tool-call limit, and treat retrieved text as untrusted input. The 429 guide covers retry behaviour when a tool loop hits a rate limit.

2027-proofing

  • Keep the interface. OpenAI-compatible chat and tools mean the same client works across providers.
  • Keep the model map in config. Planner and executor IDs should be environment variables, not string literals scattered through the code.
  • Keep the eval set. Fifty real tasks with a pass/fail rubric are the only reliable way to compare next year's models.
  • Keep the budget guard. A new model with a lower price can still cost more if it retries more often.
  • Keep the exit path. One base URL, one key and a model map are enough to move providers.

For the buying criteria behind those choices, see the 2027 AI model buyer's guide and the coding model guide.

Frequently asked questions

Do I need an agent framework for this example?

No. The example uses the OpenAI Python SDK and two model calls. A framework helps with persistence, retries and tracing, but the planner/executor pattern works without one.

Which models should plan and execute?

Use a frontier reasoning model for planning, debugging and review, and a cheaper fast model for bounded edits, summaries and repetitive steps. Test both on your own tasks before fixing the routing.

How do I add tools to the agent?

Send an OpenAI tools schema, execute the returned tool call in your code, and send the result back as a tool message. Validate arguments and set a per-run tool-call limit.

How do I control agent cost?

Set a token budget per run, cap output tokens, route routine steps to a cheap model, and stop the loop when the budget or step limit is reached. Log tokens and retries per solved task.

Will this pattern still work in 2027?

The model names will change, but the pattern should survive: one OpenAI-compatible interface, a planner tier, an executor tier and a budget guard. Keep the model map in configuration, not in code.

Can I run the executor locally?

Yes. Point the executor client at a local OpenAI-compatible server such as Ollama or LM Studio and keep the planner on a hosted model when policy allows. The request shape stays the same.

Is this code production-ready?

No. It is a minimal pattern. Add timeouts, retries with backoff, structured logging, per-user budgets, secret management and an evaluation set before production.

Run the example on current models

Start free, then move to Hobby or Starter when the agent's token volume justifies a flat plan. No per-token overage on self-serve plans.

Start free → See plans

Reviewed 20 November 2026. The code is a minimal pattern, not a production agent. Model IDs, prices and limits are a dated snapshot; verify current terms before deploying.