Delegating tasks to agents on the device¶
This page covers how one agent hands a task to another agent on the same computer with Fadenstack.Agents: for example a desktop agent that gives Office work to the add-in agent running in Word.
IAgentDelegate and its request and result types are in Fadenstack.Agents. The implementation (DelegationHost, LocalAgentDelegate, DelegateToolModule) is in Fadenstack.Agents.Delegation, a package for applications that is not on nuget.org (Getting the package).
The other agent runs the task as a new session of its own: its own server agent, tool contract, tool modes and approvals. Only the task text and the references you choose go over, and only its final answer comes back. An approval the other agent needs is asked of the caller's person.
In the add-in: take tasks¶
Start a DelegationHost once the add-in's agent is ready. It registers the agent in the device agent registry with a short card, and listens on a local pipe that only the current OS user can open. The first message on the pipe must carry a secret that exists only for this launch, and it is written to the registry folder, which only the same user can read.
using Fadenstack.Agents.Delegation;
using Fadenstack.Agents.Registry;
await agent.StartAsync();
var host = new DelegationHost(agent, new DeviceAgentRegistry(), new DelegationHostOptions
{
Name = "Word",
Description = "Reads and edits the open Word document.",
Skills = new[] { new AgentCardSkill("Comments", "Adds and answers comments") },
});
host.TaskChanged += (_, e) => pane.Show(e.Task.Label, e.Task.StatusText); // "Task from Desktop agent"
host.Start(); // dispose the host when the add-in closes
One task runs at a time; another is rejected as busy. A task that runs longer than TaskTimeout, or an approval nobody answers within ApprovalTimeout, ends or is denied. TaskChanged is raised on a background thread.
In the caller: hand a task over¶
LocalAgentDelegate implements IAgentDelegate. It finds the agent in the registry, sends the task and relays progress and approvals. An agent that is not running is a result, not an exception.
var delegation = new LocalAgentDelegate(new DeviceAgentRegistry(), "desktop-assistant", "Desktop agent");
var result = await delegation.RunAsync(
new DelegationRequest("word-assistant", "Summarise the open contract.") { References = new[] { "contract.docx" } },
new DelegationCallbacks
{
Approve = (request, token) => ShowApprovalCard(request, token), // returns an ApprovalDecision
Status = status => ShowProgress(status.Text),
},
cancellationToken);
// result.Outcome: Completed, Failed, Canceled, Rejected or NotRunning; result.Text is the answer or the reason
An approval with ForSession ("for this task") answers that tool's later calls in the same task without asking again, except where the other agent asks every time: DelegationApprovalRequest.AsksEveryTime is true for an admin's rule, the author's approval: always, a destructive or unclassified tool, and for an agent too old to say. Hide "for this task" on such a card; an approval of it covers that one call, and the next call is asked again (Tools, the calls that always ask).
As a tool: delegate¶
DelegateToolModule gives the model one delegate(agent, task, references) tool for all other agents. The agent argument is an enum of the slugs in the agent profile's ui.delegates, which is also the allowlist; with none, or with a tool contract that does not list delegate, the tool is not offered. The description lists each agent as slug: name, summary, taken from the card of the agent when it is running. The tool is class write, and the answer comes back fenced as untrusted content.
var agent = FadenstackAgent.CreateBuilder()
.UseClient(client).UseAgent("desktop-assistant")
.Use(new DelegateToolModule(delegation, new DelegateToolOptions
{
FromAgent = "desktop-assistant",
Approve = (request, token) => ShowApprovalCard(request, token),
Names = new Dictionary<string, string> { ["word-assistant"] = "Word" },
}))
.Build();
Each call is reported to the server as a tool.executed event for the tool delegate (name, outcome, duration), never with the task or the answer. With ReportDelegations the module also sends an agent.delegated event (from, to, task id, outcome, duration) once the server accepts that kind.
On the wire¶
The pipe carries A2A 1.0 over JSON-RPC, one request or response per line, after a hello with the secret of the launch. The A2A library (A2A, in the Fadenstack fork until upstream ships a netstandard2.0 build, a2aproject/a2a-dotnet issue #197) serves the agent: the methods are SendStreamingMessage, CancelTask, GetTask and GetExtendedAgentCard. An approval is the task state input-required with a data part {approvalId, tool, toolClass, summary, argumentsPreview, asksEveryTime}; only asksEveryTime: false lets the caller answer later calls of the tool for the task, and a missing flag (an older agent) counts as true. The answer is a message on the same task with a data part {approvalId, decision}, where the decision is once, chat or deny. The answer is an artifact with one text part, and the task ends completed.
Getting the package¶
Fadenstack.Agents.Delegation and the A2A library it uses are on the fadenstack organisation's GitHub Packages feed: A2A in the Fadenstack fork, which has the netstandard2.0 build that .NET Framework hosts need (a2aproject/a2a-dotnet issue #197). Map both packages to that feed, so neither can come from anywhere else:
<configuration>
<packageSources>
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
<add key="fadenstack" value="https://nuget.pkg.github.com/fadenstack/index.json" />
</packageSources>
<packageSourceMapping>
<packageSource key="nuget.org">
<package pattern="*" />
</packageSource>
<packageSource key="fadenstack">
<package pattern="A2A" />
<package pattern="Fadenstack.Agents.Delegation" />
</packageSource>
</packageSourceMapping>
</configuration>
The feed needs a GitHub token that may read the organisation's packages. In GitHub Actions that is the job's GITHUB_TOKEN, once both packages give the repository read access.
While A2A is a preview, a stable SDK version has this package as a preview of it: with SDK 0.3.0, reference Fadenstack.Agents.Delegation 0.3.0-preview. A prerelease of the SDK has the same version for both.