Agent Orchestration
Learn how a chat request selects an Agent Core, assembles tools, executes model steps, and finalizes safely.
UnieAI Studio orchestrates the model and its tools inside a Chat Completions request. The runtime resolves the custom model and Agent Core version, loads the resources available to that request, builds the system prompt and tool schemas, and repeats “model decision → tool execution → result” until the model answers or a limit is reached.
The current Agent Core 1.0 is a request-scoped loop in the runtime. It does not use a database job queue, session lease, worker heartbeat, or waiting_for_permission state. The loop ends when the HTTP request ends, is cancelled, or the runtime stops.
Request flow
1. Authentication and version selection
The runtime first authenticates the API key, caller, and custom-model access. It then selects a core from the custom model's AI Engine setting. A version explicitly selected on the custom model takes precedence over the platform default; choosing the platform default follows the administrator's setting.
The current UI offers the platform default and Agent Core 1.0 (in-house agentic loop). If an existing model still stores a legacy engine value, the UI displays that value so it can be switched to a current option.
2. Build request context
For the request, the runtime loads:
- The custom model, base model, and workspace settings
- The system prompt, core memory, and relevant retrieval memory
- Authorized knowledge bases, SQL connections, web search, APIs, remote MCP servers, and skills
- Ontology or other working information needed by enabled features
- Caller, timeout, step, and cancellation information
Independent tool sections degrade separately when possible. A failure in the base model, authentication, or required runtime data can still fail the request.
3. Assemble the toolset
Only capabilities allowed by configuration and permission become function-calling schemas. Agent Core 1.0 combines eligible knowledge, SQL, web-search, API, MCP, skill, todo, memory, and optional sub-agent tools into a request-specific toolset.
Tool names and arguments pass through validation and repair. An invalid name, malformed arguments, or missing required property is returned to the model as an actionable error; unknown tools are not forwarded blindly to external services.
4. Run the model-tool loop
Each model step can:
- Return plain text and end the loop
- Request one or more tool calls
- Return reasoning content together with tool calls
Multiple calls in one step execute through a bounded concurrency pool, while results are appended in their original order. The default Agent Core 1.0 tool concurrency is 4 and can be changed by deployment configuration.
After execution, the runtime appends an assistant message containing tool_calls and one tool message for each result. The next model step can therefore use earlier results without a separate server-session state machine.
Steps, timeouts, and cancellation
Maximum steps
Agent Core 1.0 defaults to 12 model steps. A custom model can set its maximum under Behavior → Agent Loop, and deployment configuration can change the default.
The final normal step keeps the tool schemas visible but instructs the model to stop using tools and summarize:
- Completed work and key results
- Incomplete work
- Recommended next steps
If the model still requests tools, the runtime does not execute them. It appends synthetic “not executed” results and grants one final step with all tool schemas removed, giving the model a chance to return text.
Timeouts
- Each model step is constrained by the upstream request timeout and any overall deadline.
- Tools can have their own timeout. API and MCP operations can use operation or server values, or the custom-model defaults.
- Agent Core 1.0 also has a loop-level per-tool backstop, 60 seconds by default. A custom-model tool-timeout setting can override it.
- A timeout becomes a tool error that the model can answer from, work around, or retry with a narrower request.
Cancellation
When a user stops generation in the Playground or a client aborts the HTTP connection, the cancellation signal propagates to model calls, tools, and sub-agents. New tools that have not started are skipped. Whether an operation already sent to an external system can be cancelled depends on that service.
Client cancellation does not guarantee that an external write is rolled back. Implement idempotency keys, transactions, or compensation for SQL, API, and MCP tools that can cause side effects.
Repetition protection
Agent Core 1.0 uses two layers by default:
| Condition | Default behavior |
|---|---|
| Same tool with identical arguments | Skip execution from the third occurrence and tell the model to reuse the result or change approach |
| Same tool called consecutively, regardless of arguments | Warn at 5 calls and force finalization at 7 |
Deployments can adjust these values. This protection compares tool names and arguments; it does not replace rate limits, spending controls, or idempotency in the external service.
Context compaction
Before the loop, the runtime estimates whether the system prompt and chat history fit the available context. It compacts older conversation when needed while retaining recent content. It checks again after tool execution and can prune older tool results.
If the upstream model still reports a recognized context overflow, the runtime forces a reduction and reissues that model step once. Compaction events can appear in the Playground through agent metadata.
Upstream retry and error isolation
The model-call layer performs bounded backoff retries for selected transient 429, 5xx, DNS, connection-reset, and step-timeout failures. It does not blindly resend invalid requests, authorization failures, or the same overflowing context.
Tool failures are normally normalized into tool messages so the model can choose the next action. If the entire loop fails irrecoverably:
- A streaming request attempts to close SSE correctly instead of leaving it hanging
- A non-streaming request can return usable text already produced
- If no usable text exists, the API returns an appropriate error
Applications must not assume every failure always has a natural-language final answer.
Streaming events
Streaming uses OpenAI-compatible SSE content chunks and can include UnieAI metadata:
| Event | Purpose |
|---|---|
reasoning_content | Reasoning fragments from supported models |
agent_metadata | Tool lifecycle, SQL, search, sub-agent, compaction, and warning events |
guardrail_metadata | Results from enabled guardrails |
Normal content | User-visible answer text |
The Playground builds its timeline from these events. A third-party OpenAI client that ignores unknown fields can still consume the answer. An application that wants to display agent progress must parse the extensions itself.
Where guardrails run
When guardrails are configured and enabled, input checking occurs before the tool loop is built. Output checking occurs only when configured to apply to output: non-streaming answers are checked as a whole, while streaming answers use an output gate to check visible text in windows.
If guardrails are disabled, configuration cannot be loaded, or the checking service follows a fail-open policy, do not claim that content was necessarily blocked. High-risk tools still require authorization and argument validation at the tool boundary.
Sub-agent orchestration
A sub-agent is an isolated agent loop created inside the parent request, not a persistent background job. It inherits the remaining deadline and cancellation signal and uses its own history with a lower step cap. It can use eligible data tools but cannot create another sub-agent or share the parent's todo state.
The parent receives only the distilled conclusion from each helper. Timeline events can be tagged with a taskId and depth, while model and tool usage is merged into the parent request usage.