Agent API (organizations)

On dianqi.zsopc.com, an organization can create agents: a preset persona (system prompt), a locked model, web-search and image-generation switches, and attached knowledge bases. The Agent API exposes one agent much like a Dify "app" — you get an API key bound to that agent, call it with the standard OpenAI protocol, and the backend applies the agent's entire configuration for you.

One agent key = one agent. The caller doesn't need to know the persona, model or knowledge bases — those come from the agent's configuration, and the client only sends conversation content.

Getting an agent API key#

Agent API keys are issued from the organization console — they are not self-service.

• Org admins / owners: console → Agent API → pick a published organization agent → issue. The plaintext is shown once, and can be viewed again from the list at any time.
• Org employees: open an agent in the agent gallery → "Request an external API key" → an admin approves and issues it in the console (setting a spend cap at issue time) → find and use it on your own API Keys page.

Issued keys use the same format as ordinary keys (sk-gpushare- plus 64 hex characters); for auth see Authentication (Authorization: Bearer, x-api-key or ?key=).

An agent API key is an org asset: usage is billed to the organization account and constrained by the org model allowlist, independent of the personal quota of whoever issued it.

Calling it#

The endpoint is always POST https://dianqi.zsopc.com/v1/chat/completions, and the body is the standard OpenAI Chat Completions shape. The model field is ignored (the agent has a locked model), so any placeholder works — "agent" is the convention.

curl#

curl https://dianqi.zsopc.com/v1/chat/completions \
  -H "Authorization: Bearer $AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agent",
    "messages": [{"role": "user", "content": "What is the expense reimbursement policy?"}]
  }'

Streaming (SSE)#

curl https://dianqi.zsopc.com/v1/chat/completions \
  -H "Authorization: Bearer $AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"agent","messages":[{"role":"user","content":"Hello"}],"stream":true}'

OpenAI Python SDK#

from openai import OpenAI

client = OpenAI(
    api_key="sk-gpushare-...",            # the agent API key
    base_url="https://dianqi.zsopc.com/v1",
)

resp = client.chat.completions.create(
    model="agent",                         # placeholder; the agent locks the model
    messages=[{"role": "user", "content": "What is the expense reimbursement policy?"}],
)
print(resp.choices[0].message.content)

Any OpenAI-compatible client (LangChain, n8n, Coze, your own backend…) works by pointing at https://dianqi.zsopc.com/v1 with this key — no code changes.

What the backend does#

Before forwarding upstream, each request goes through:

• Persona injection: the agent's system prompt is inserted as the first system message (taking precedence over any system message the client sent).
• Model locking: the real model comes from the agent's configuration (agent.model_id, falling back to the org default then the platform default). The client's model field is ignored.
• Knowledge retrieval: if the agent has knowledge bases attached, the backend searches them using your most recent user message (scoped to what the agent's creator can see), injects the relevant pages into context, and then answers (single-round RAG).
• Capability switches: when the agent has web search or image generation enabled and the chosen model supports it, the matching built-in tool is enabled automatically. Any tools / functions the client sends are ignored — capabilities come from the agent's configuration, and that's a security boundary.
• Temperature: the agent's temperature applies unless the client sets one explicitly.
• Multimodal: OpenAI content arrays (including image_url) are supported, but only when the agent's model has vision — otherwise you get a 400.

Multi-turn is stateless#

v1 keeps no server-side session storage. For multi-turn conversations, carry the full context in messages[] exactly as you would against OpenAI directly. conversation_id isn't supported yet.

Caching tip: for multiple turns in one conversation, send a session_id (or conversation_id) request header — the backend uses it to pin the conversation to a fixed upstream account, hitting the prefix cache and substantially reducing the cost of repeated context. Without it, every turn is recomputed at full price.

Billing#

• Billed per token against the organization account (the org balance, or the key's funded reserve), at the same rates as ordinary models — see Models.
• Keys requested by employees must have a spend cap (a funded reserve); keys an admin issues directly may have no cap and draw on the org balance.
• Usage is aggregated per agent, and admins can see each agent's external API consumption in the console.
• At-least-once: a client retry after a network interruption bills twice, so deduplicate on the client side.

Error codes#

The error body matches every other endpoint (see Error codes): {"error": {...}} in the OpenAI shape.

Scope restriction (fail-closed): an agent API key can call only POST /v1/chat/completions. Requests to /v1/messages, /v1/responses, /v1beta/..., /v1/images, /v1/videos, /v1/embeddings, the knowledge-base REST/MCP endpoints or anything else are rejected — it never degrades into an unrestricted org key.

Lifecycle and security#

• Valid until revoked: keys don't expire by default and keep working until an admin revokes or deletes them in the console (revocation takes effect immediately).
• Plaintext viewable any time: admins can re-reveal any agent key in their organization, and employees can re-reveal their own, from the console (stored encrypted server-side). Every view is audited.
• A note on knowledge-base exposure: callers of an external API may be anonymous, and in principle they can coax an agent into repeating the content of an attached knowledge base. Attaching a knowledge base means accepting that its content is reachable through the agent's responses — for sensitive bases, state the constraints in the agent's persona, or don't attach them to a publicly exposed agent.
• Auditing: issuing, approving, revoking and revealing plaintext are all recorded append-only and visible to admins.