Agent Hub

Key Concepts

Agent Hub is organized around a small number of building blocks that compose together. Understanding these primitives will help you design agents that are secure, maintainable, and easy to iterate on.

Provider Keys

A provider key represents your organization's credentials for an LLM provider such as OpenAI or Anthropic. Keys are encrypted at rest and are never exposed in API responses. Each key is scoped to a single provider and can be rotated independently without affecting any running agents.

LLM Configs

An LLM config is a named configuration that pairs a provider key with a specific model and a set of inference parameters such as temperature, max_tokens, and top_p. Separating model configuration from agent logic means you can swap models or tune parameters without changing a single line of prompt.

Agent Configs

An agent config defines the agent itself. It includes the system prompt, a primary LLM config, an optional fallback LLM config for resilience, tool iteration limits, and a timeout. Think of it as the blueprint from which conversations are created and invocations are run.

Tool Access

Tool access is resolved from the agent's IAM grants. Each catalog tool declares a required permission and an action type such as read, create, update, delete, send, or execute. IAM remains the hard authorization layer; action types are taxonomy for product presentation and future platform-owned modes.

Conversations (separate service)

Conversations are not owned by Agent Hub. They live in the dedicated Conversations service, which is the universal substrate for any dialogue on the platform — human↔human, human↔agent, agent↔agent. When you invoke an agent, Agent Hub creates (or continues) a conversation in that service and returns its ID. All messages, participants, attachments, and real-time streaming are then handled there. See the Multi-agent collaboration concept for why this separation matters.

Memory

Agents have long-term memory through Buckets-backed notes and recall, plus a transparency contract that makes the memory state visible at every turn. This is its own design surface — see the Agent memory concept for the model.

Access Grants

Agents, skills, LLM configs, and provider keys are separate connection-gated zones. Connect a principal to each target first, resolve permission UUIDs from its access/resource-types catalog, then grant access through the matching zone surface.

When granting across multiple roots or permissions, prefer one grouped batch request over sequential single-grant calls. Agent Hub exposes POST /api/v1/agents/access/agents/grants/batch, POST /api/v1/agents/access/skills/grants/batch, POST /api/v1/agents/access/llm-configs/grants/batch, and POST /api/v1/agents/access/provider-keys/grants/batch. Each accepts grouped operations and returns ordered per-grant created, already_exists, or failed outcomes.

Budgets & Allocations

An LLM configuration budget is the shared hard ceiling for every agent allowed to use that configuration. It can limit estimated USD spend and exact combined input/output tokens on a daily, weekly, or monthly reset window. An agent may also have a recurring cap across every configuration. Applicable configuration, agent, and principal spend limits intersect; the first limit reached stops new model calls.

Conversation limits are separate from recurring spend. Each new conversation session starts its own estimated-cost, token, and session-time counters. These limits apply uniformly to every conversation with the agent and are not affected by a daily, weekly, or monthly reset window. New agents start with conservative limits of $5 estimated cost, 250,000 tokens, and 60 minutes per conversation. Platform safety ceilings are $100, 1,000,000 tokens, and 1,440 minutes per conversation; recurring caps cannot exceed $10,000 or 100,000,000 tokens.

Principal allocations

Each agent/configuration allocation can be distributed again to authorized IAM principals: members, other agents, API keys, and automations. Principal shares use the same fixed, automatic, locking, and frozen-window rules as agent shares. Automation usage is cumulative across every execution and invoke-agent node for that automation principal during the reset window. Principal rows divide recurring spend only; per-conversation limits remain agent-wide.

Agents may use multiple configurations. Allocations remain separate per configuration; they are never added into one implicit pool. When the same model is available through several configurations, model selectors show each configuration route and label low or exhausted routes. The platform does not silently choose the route with the largest remaining budget.

Fixed and automatic shares

The allocation matrix lists connected agents. Only agents holding agents:llm-configs:use can receive a share. Everyone starts equal. Editing an unlocked percentage proportionally rescales the other unlocked agents in real time; locked rows remain unchanged. Cost and token estimates follow the pool draft while you type.

The pool and complete allocation policy save atomically. Once spending starts, the platform freezes the whole eligible-agent cohort and all resolved limits for that reset window. Draft edits and newly granted agents take effect at the next boundary. Revoked access stops immediately, and its active share remains unused instead of being redistributed.

Input/output tokens and platform-derived cost are committed after every successful provider call, so the dedicated configuration and agent Usage tabs update without waiting for a multi-round run to finish. Agent usage can be grouped by configuration, model, principal, conversation, and automation. Authorized conversation viewers see the conversation token and estimated-cost summary; automation run events include per-invoke tokens and estimated cost. Budget changes, usage, and blocked out-of-budget attempts are also available in Activity and Event Streams.

See the Budgets API reference for endpoints and schemas.

How Invocation Works

When you invoke an agent, the platform orchestrates a multi-step process that transforms your message into a fully reasoned, tool-augmented response. Here is what happens end-to-end:

1. Request. Your application sends a POST request to the invoke endpoint with the user's message.
2. Configuration resolution. The platform resolves the agent config and its associated LLM config, loading the correct model, parameters, and provider credentials.
3. System prompt assembly. A complete system prompt is assembled from the agent's identity instructions, organizational context, selected skills, and a compact resident-tool guide. Additional tools and platform manuals are discovered on demand rather than embedded exhaustively.
4. Completion loop. The platform calls the LLM. If the model responds with tool calls, those tools are executed and the results are fed back for another completion — this loop continues until the model produces a final text response or a configured iteration limit is reached.
5. Streaming response. As the LLM generates tokens, they are streamed in real-time over a WebSocket connection so your UI can render responses progressively.

Here is a minimal example of invoking an agent via the API:

curl -X POST https://platform.ergondata.ai/api/v1/agents/agents/{agent_id}/invoke \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "input": { "prompt": "Summarize the latest support tickets" },
    "source_type": "platform"
  }'

Conversations

What this means in practice:

• Creating a conversation. Agent Hub does this for you when you call invoke — the response includes a conversation_id and the first message_id. You can also create conversations directly through the Conversations API for human-only or multi-participant scenarios.
• Sending messages. Use the Conversations API (POST /api/v1/conversations/.../messages). When the message arrives in a conversation that has an agent participant, Agent Hub picks it up and processes it.
• Streaming responses. Connect to the Conversations real-time stream (WebSocket) for the conversation. Agent token-by-token deltas, tool calls, and final messages are delivered there.
• Retrieving history. The Conversations service is the source of truth for the transcript. Agent Hub only owns the configuration and the invocation.

See the Conversations API reference for the full surface, and the Multi-agent collaboration concept for how agents discover each other and hand off work in a conversation.

Privacy lock & cross-conversation behavior

An agent can be privacy-locked so every conversation it joins is forced public. The toggle is governed by agents:privacy:manage and keeps the agent's activity observable. Separately, agents:conversations:view grants read-only visibility into an agent's public conversations for supervisors who don't hold a direct grant on each thread.

When an agent surfaces or cross-posts content from one thread into another, the message carries a server-set origin provenance marker, and the move is gated by the destination-subset privacy rule (see the Conversations privacy guide).

Agent-to-agent dialogue

Autonomous agent-to-agent dialogue is off by default. When a company enables it, an agent-sent message is relayed to the other agent participants of a thread (never the sender), bounded by loop-safety budgets: a cap on consecutive agent turns and a rate cap per rolling window, both clamped to platform limits. When a budget is exhausted, the thread gets a single non-triggering pause status and waits for a human, who resets the budget. Configure it with the Conversations A2A settings endpoints.

Integration Patterns

Agent Hub is designed to be invoked from anywhere in the platform. Here are the most common integration patterns:

Direct API Invocation

The simplest pattern — your application creates a conversation and invokes the agent directly via the REST API. This is ideal for service-to-service integrations where you control both sides of the interaction.

Inbound Email Routes

Agent Hub surfaces auto-reply routes, but their endpoints and records are owned by Channels . An agent manager controls route creation and deletion, active/paused status, reply address, and the max_auto_replies_per_thread policy (1–100, default 10). The receiving-address manager independently controls the authoritative address_status of allowed or blocked; a blocked address suppresses auto-reply even when the agent route is active.

On inbound email, Channels emits a route snapshot. Conversations creates or resumes the single conversation bound to that channel thread, expands notify users and teams into participants, selects at most one auto-reply agent, and materializes attachments through Buckets. Agent Hub is then triggered only by the resulting Conversations message event; it no longer receives a direct channel trigger or base64 attachment payload.

Workflow Automations

Workflows can invoke agents as part of phase transitions. For example, when a support ticket moves to the “triage” phase, a workflow automation can invoke an agent to classify the ticket, suggest a priority, and draft an initial response. See the Workflows guide for details.

WebSocket Streaming for Real-Time UIs

For interactive user interfaces, connect to the WebSocket stream to display agent responses as they are generated. This provides a chat-like experience where tokens appear progressively. See the Webhooks guide for event-driven patterns that complement streaming.