Skip to content

Support invoke_agent in direct runtimes #3587

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kwakayama merged 4 commits into from
Aug 11, 2026
Merged

Support invoke_agent in direct runtimes #3587

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
6d379f8
Support invoke_agent in direct runtimes
kwakayama Aug 11, 2026
02f4df8
Address invoke_agent review feedback
kwakayama Aug 11, 2026
dfc38e3
Make invoke_agent tests cross-runtime
kwakayama Aug 11, 2026
d339b92
Propagate agent tool cancellation
kwakayama Aug 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions docs/api-reference/veryfront/agent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -531,7 +531,7 @@ Input delivered to a hosted agent-service detached execution callback.
| `addFirstTurnStarterIntentRootOwnershipReminder` | Add first turn starter intent root ownership reminder helper. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/conversation/delegation-policy.ts#L225) |
| `addLoadSkillContinuationReminder` | Add load skill continuation reminder helper. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/conversation/delegation-policy.ts#L289) |
| `addSlashCommandArtifactReminder` | Add slash command artifact reminder helper. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/conversation/delegation-policy.ts#L312) |
| `agent` | Agent helper. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/factory.ts#L380) |
| `agent` | Agent helper. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/factory.ts#L391) |
| `agentAsTool` | | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/composition/composition.ts#L63) |
| `appendAgentServiceChildMirrorChunk` | Append hosted child mirror chunk. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/hosted/child-mirror.ts#L180) |
| `appendConversationRunEvents` | Append conversation run events. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/conversation/durable.ts#L1144) |
Expand All @@ -545,7 +545,7 @@ Input delivered to a hosted agent-service detached execution callback.
| `bootstrapConversationAgentRun` | Bootstrap conversation agent run helper. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/conversation/bootstrap.ts#L319) |
| `bootstrapHostedChildRun` | Bootstrap hosted child run helper. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/hosted/child-bootstrap.ts#L54) |
| `buildAgentCallContext` | Builds the complete system-message set for one provider call. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/runtime/call-context.ts#L127) |
| `buildAgentDelegateTools` | Builds the opt-in delegate tools for a coordinator agent. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/runtime/agent-delegation.ts#L84) |
| `buildAgentDelegateTools` | Builds the opt-in delegate tools for a coordinator agent. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/runtime/agent-delegation.ts#L158) |
| `buildAgentRunTraceAttributes` | Builds agent run trace attributes. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/hosted/trace-attributes.ts#L181) |
| `buildAgUiBrowserFinalizeResponse` | Response payload for build AG-UI browser finalize. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/ag-ui/browser-encoder.ts#L415) |
| `buildAgUiSseTraceSignature` | Build a compact ordered event-type signature for regression checks. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/ag-ui/sse-parser.ts#L75) |
Expand Down Expand Up @@ -1229,7 +1229,7 @@ Input delivered to a hosted agent-service detached execution callback.
| `BootstrapHostedChildRunResult` | Result returned from bootstrap hosted child run. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/hosted/child-bootstrap.ts#L30) |
| `BootstrappedHostedChatExecutionRuntime` | Public API contract for bootstrapped hosted chat execution runtime. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/hosted/chat-execution-runtime.ts#L185) |
| `BuildAgentCallContextInput` | Input payload for build agent call context. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/runtime/call-context.ts#L50) |
| `BuildAgentDelegateToolsInput` | Input payload for build agent delegate tools. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/runtime/agent-delegation.ts#L22) |
| `BuildAgentDelegateToolsInput` | Input payload for build agent delegate tools. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/runtime/agent-delegation.ts#L96) |
| `BuildChatStreamChunkMessageMetadataInput` | Input payload for build chat stream chunk message metadata. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/chat/chat-ui-message-helpers.ts#L9) |
| `BuildDetachedFallbackChunksInput` | Input payload for build detached fallback chunks. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/hosted/finalized-message.ts#L60) |
| `BuildDetachedFallbackMessageInput` | Input payload for build detached fallback message. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/hosted/finalized-message.ts#L29) |
Expand Down Expand Up @@ -1382,7 +1382,7 @@ Input delivered to a hosted agent-service detached execution callback.
| `DefaultResearchArtifactLogger` | Public API contract for default research artifact logger. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/artifacts/default-research-artifact-support.ts#L24) |
| `DefaultResearchArtifactPaths` | Public API contract for default research artifact paths. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/artifacts/default-research-artifact-policy.ts#L67) |
| `DefaultResearchArtifacts` | Public API contract for default research artifacts. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/artifacts/default-research-artifact-support.ts#L13) |
| `DelegateAgentResolver` | Resolves a registered agent by id (defaults to the global registry). | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/runtime/agent-delegation.ts#L11) |
| `DelegateAgentResolver` | Resolves a registered agent by id (defaults to the global registry). | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/runtime/agent-delegation.ts#L28) |
| `DerivedAgentServiceAgUiChatContext` | Context for derived hosted AG-UI chat. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/hosted/ag-ui-chat-request.ts#L49) |
| `DerivedHostedAgUiChatContext` | Context for derived hosted AG-UI chat. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/hosted/ag-ui-chat-request.ts#L49) |
| `DetachedFallbackMessageState` | State for detached fallback message. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/agent/hosted/finalized-message.ts#L44) |
Expand Down
15 changes: 8 additions & 7 deletions docs/guides/multi-agent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,13 +130,14 @@ Break the task down. Use agent_researcher to gather facts, then agent_writer to
produce the final copy.
```

Set `delegates: []` when an agent must not delegate. Hosted runtimes retain the
legacy generic `invoke_agent` tool only for older definitions where
`delegates` is absent; direct runtimes do not add it automatically.
Self-delegation and delegate ids that cannot form a valid provider tool name
are rejected with explicit diagnostics. Declare direct tools by name when
using `delegates`; `tools: true` is intentionally rejected because it would
hide the agent's capability boundary.
Set `delegates: []` when an agent must not delegate. `invoke_agent` is the
generic platform tool for dynamic agent selection. Enable it explicitly in a
direct runtime with `tools: { invoke_agent: true }`; hosted runtimes expose it
when generic delegation is allowed and `delegates` is absent. Self-delegation
and delegate ids that cannot form a valid provider tool name are rejected with
explicit diagnostics. Declare direct tools by name when using `delegates`;
`tools: true` is intentionally rejected because it would hide the agent's
capability boundary.

Hosted nested delegation carries trusted invocation lineage from parent to
child runs. The root conversation and run stay stable, the immediate parent is
Expand Down
70 changes: 59 additions & 11 deletions src/agent/factory.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ import { tool, toolRegistry } from "#veryfront/tool";
import { defineSchema } from "#veryfront/schemas/index.ts";
import { VeryfrontError } from "#veryfront/errors";
import { getEffectiveAgentSystem } from "./runtime/effective-agent-system.ts";
import { getAvailableTools } from "./runtime/tool-helpers.ts";
import { agentRegistry } from "./composition/index.ts";
import { agent } from "./factory.ts";
import type { AgentConfig, AgentResponse } from "./types.ts";
Expand Down Expand Up @@ -375,18 +376,65 @@ description: Excluded skill
assertEquals(toolRegistry.has("agent_ingestion-agent"), false);
});

it("materializes explicitly requested invoke_agent for direct runtimes", async () => {
const assistant = agent({
id: "generic-orchestrator",
system: "Invoke registered specialist agents.",
skills: [],
tools: { invoke_agent: true },
});

const definitions = await getAvailableTools(assistant.config.tools, {
callerAgentId: assistant.id,
includeIntegrationTools: false,
});

assertEquals(definitions.map((definition) => definition.name), ["invoke_agent"]);
});

it("suppresses generic invoke_agent when delegates are explicitly scoped", async () => {
for (
const [id, delegates, expectedTools] of [
["empty-delegate-scope", [], []],
["fixed-delegate-scope", ["ingestion-agent"], ["agent_ingestion-agent"]],
] as const
) {
const assistant = agent({
id,
system: "Delegate only within the explicit scope.",
skills: [],
delegates: [...delegates],
tools: { invoke_agent: true },
});

const definitions = await getAvailableTools(assistant.config.tools, {
callerAgentId: assistant.id,
includeIntegrationTools: false,
});

assertEquals(definitions.map((definition) => definition.name), [...expectedTools]);
}
});

it("rejects delegates combined with the implicit all-tools selector", () => {
assertThrows(
() =>
agent({
id: "broad-orchestrator",
system: "Delegate specialist work.",
delegates: ["ingestion-agent"],
tools: true,
}),
Error,
"cannot combine delegates with tools: true",
);
for (
const [id, delegates] of [
["empty-broad-orchestrator", []],
["broad-orchestrator", ["ingestion-agent"]],
] as const
) {
assertThrows(
() =>
agent({
id,
system: "Delegate specialist work.",
delegates: [...delegates],
tools: true,
}),
Error,
"cannot combine delegates with tools: true",
);
}
});

it("uses the default system prompt before an available skill catalog", async () => {
Expand Down
Loading