Agent harness: execution model and Tool Call outcomes
This section explains the Task execution model and Tool Call outcomes for the Duale AI Agent harness.
This page covers the Agent harness execution model, Task lifecycle, Tool Call outcomes, and the separation of capability, authority, and Effect.
- Task lifecycle from request to outcome.
- Execution model terms and definitions.
- Tool Call outcomes and their next actions.
- Separation of capability, authority, and Effect.
Summaries were generated by AI.
Duale AI runs Tasks for your application. You submit an objective with its starting material, an answer format, and a deadline. The Task works toward that objective with Tools, and your application receives one outcome. The Agent harness is how Tasks behave; it is not a service or an API resource that you call.
A Task uses Tools from three places: Built-in Tools that Duale AI supplies, SDK Tools that your application serves, and MCP Tools from the servers you connect. A Task request carries no Tool definitions and cannot add, remove, or narrow Tools. The model chooses which Tool to use, and an available Tool can go unused. Tools explains each source.
An Agent is software that works toward an objective on behalf of an accountable person or organization. An Agent Identity supplies the credentials, attribution, and Platform permissions that an application uses. It does not define the application’s behavior. Identity owns credentials and access; your application keeps any behavior-version records it needs.
Follow one Task from request to outcome
Your application generates and keeps the Task ID, can show streamed answer text, and serves the Tool requests for its SDK Tools. It receives exactly one Task Outcome: a completed answer, a failure, or a stopped Task. The requested answer format or schema applies to the completed answer. A Tool Call or a Tool Result alone does not prove that an external operation succeeded.
Task execution explains the deadline, Stop, and delegated work. The SDK reference defines the submission, streaming, result, and Stop methods.
Use the current execution model
| Term | What it means |
|---|---|
| Task Input | The instruction, content, and data references supplied for one objective |
| Task | A request with its own identifier, deadline, response contract, and outcome |
| Task history | The instructions, messages, Tool Calls, and Tool Results that a Task records |
| Model turn | One step in which the model reads the Task’s context and chooses its next action. One model turn can make several provider requests |
| Tool | A named capability that can retrieve information or request an operation |
| Built-in Tool | A Tool that Duale AI supplies to Tasks. Built-in Tools lists each one and the page that owns its behavior |
| Tool Call | A request to use a Tool with particular arguments |
| Tool Result | The Tool’s reported response, which the Task can use to continue its work |
| Tool Call outcome | How a Tool Call ended, as the Dashboard shows it: Succeeded, Failed, Outcome unknown, Not executed, or Blocked. Read a Tool Call outcome gives the next action for each |
| Task Outcome | A completed answer, a stopped Task, or a failure with typed problem information |
| Continuation Task | A new request that builds on selected history from a previous Task |
| Recall | The Built-in Tools with which the model rereads the Task’s own earlier work and searches the requests and final answers of earlier Tasks of the same Agent Identity. What a Task can recall from earlier Tasks |
| Delegated work | A focused part of the Task’s work that the Task hands off and receives back inside the same Task. How a Task divides its work |
| To-do list | The steps a Task tracks for its own multi-step work. A continuation inherits it; your application does not read or change it |
| Executor | The Dashboard’s name for one part of a Task’s work, shown in the Task view |
Use response.next() when you want a new instruction to build on an earlier Task. The continuation has its own result,
deadline, and Stop. Context continuity explains the inherited history and
independent branches. Start a new Task with ask() when you do not want the request to inherit that Task history. A
new Task inherits nothing, but Recall can still find earlier Tasks of the same Agent Identity.
Read a Tool Call outcome
Every Tool Call ends with one outcome. The outcomes mean the same for Built-in Tools, SDK Tools, and MCP Tools, and the Dashboard Task view shows the outcome of each Tool Call.
| Outcome | What it means | What to do |
|---|---|---|
| Succeeded | The Tool reported a result. | Use the result. Verify any material change at the system that owns it. |
| Failed | The Tool ran and did not succeed, including when the target refused the request. | Fix the cause. Repeat the operation only when a repeat is safe. |
| Outcome unknown | The record does not show whether the Tool ran or whether its effect happened, for example when a request timed out after it was sent to its target. | Read the destination system before you repeat or compensate the operation. |
| Not executed | The call ended before its Tool was invoked, so the Tool had no effect. | Change the call or the request before you repeat it. |
| Blocked | Duale AI refused or limited the request under a policy or a limit, for example a disabled MCP Connection or a refused package. | Change the request, the policy, or the limit. |
- Outcome
- Succeeded
- What it means
- The Tool reported a result.
- What to do
- Use the result. Verify any material change at the system that owns it.
- Outcome
- Failed
- What it means
- The Tool ran and did not succeed, including when the target refused the request.
- What to do
- Fix the cause. Repeat the operation only when a repeat is safe.
- Outcome
- Outcome unknown
- What it means
- The record does not show whether the Tool ran or whether its effect happened, for example when a request timed out after it was sent to its target.
- What to do
- Read the destination system before you repeat or compensate the operation.
- Outcome
- Not executed
- What it means
- The call ended before its Tool was invoked, so the Tool had no effect.
- What to do
- Change the call or the request before you repeat it.
- Outcome
- Blocked
- What it means
- Duale AI refused or limited the request under a policy or a limit, for example a disabled MCP Connection or a refused package.
- What to do
- Change the request, the policy, or the limit.
The Task view shows Timed out for a Tool Call that did not answer in time. A timeout does not confirm whether the Tool succeeded, so its outcome is Outcome unknown: read the destination system before any repeat. A Tool Call that a Duale AI safety check blocks never reaches its Tool: the model reads that a safety check blocked that step, and the Task continues. Tools Analytics adds categories for MCP Connections and a confirmed success rate: Operate Tools defines them. A Tool Result is a report, not proof that an Effect occurred.
Separate capability, authority, and Effect
These properties answer different questions:
| Property | Question it answers |
|---|---|
| Autonomy | Which actions can the application choose without a fresh external decision? |
| Capability | Which operations can it request through its available Tools? |
| Platform access authorization | Which Platform resources does the caller have permission to use? |
| External-action authority | Which action and arguments does the customer system permit? |
| Effect | Which state change actually occurred? |
| Impact | What consequence can that change have for people, systems, or the business? |
- Property
- Autonomy
- Question it answers
- Which actions can the application choose without a fresh external decision?
- Property
- Capability
- Question it answers
- Which operations can it request through its available Tools?
- Property
- Platform access authorization
- Question it answers
- Which Platform resources does the caller have permission to use?
- Property
- External-action authority
- Question it answers
- Which action and arguments does the customer system permit?
- Property
- Effect
- Question it answers
- Which state change actually occurred?
- Property
- Impact
- Question it answers
- What consequence can that change have for people, systems, or the business?
An Action is an attempted operation. An Effect is a state change that actually occurs; an External Effect occurs outside the Platform. A read-only Task can choose many actions, while one Tool Call can send a message or delete information. Make the required authorization or approval part of the Tool or external system before it acts.
The effect field on a Library Grant means allow or deny; it is an access decision.
Continue with the owner of the next question:
- Task execution for deadlines, Stop, delegated work, and the Dashboard Task view.
- Context continuity for continuations and Recall.
- Tools for Built-in Tools, SDK Tools, and MCP Connections.
- Code Execution for bounded Python or JavaScript work within a Task.
- Libraries and Model routing for data and model capabilities.
- Secure integration for authorization, duplicate attempts, and uncertain external changes.