docs: proposal -- public seam for host-supplied tools at the Engine/prepare level - #161
Open
Brian Krabach (bkrabach) wants to merge 1 commit into
Open
Conversation
… level
Downstream-embedder proposal, not a spec change. We (a .dot-pipeline runner
embedding Engine per docs/INTEGRATION.md) used to reach into a hosted
session's own coordinator (session.coordinator.mount("tools", ...)) from our
turn_handler to hand it a host-declared tool -- the same call shape
amplifier_agent_http/_session_runner.py itself uses internally
(HostToolProxy, line ~134), so the mechanism is proven safe, just not public.
We deleted that reach-in on principle: coordinator is internals, not our
contract surface, and an embedder depending on it has no compatibility
guarantee.
Proposes a small, additive seam (illustrative shape: an inject_host_tools(prepared,
tools) alongside the existing inject_provider/inject_routing_matrix pattern)
and explicitly cites docs_v1/05-interface/tools.md's ToolsConfig(host_tools=[...])
as the real destination -- we intend to adopt the v1 facade the moment it
ships as code and are scoping this ask only to the gap between now and
then.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Proposal doc:
docs/HOST-TOOLS-PROPOSAL.md.Filed as a docs PR rather than an issue -- this repo's Issues are disabled,
and there's no
CONTRIBUTING.md/docs/designs/proposal process currentlyin the tree for me to match, so I picked the closest existing convention
(a flat doc under
docs/, alongsideINTEGRATION.md/ARCHITECTURE.md).Happy to move/rename/close in favor of whatever process you'd actually
prefer -- including "wontfix, wait for v1," which this doc says explicitly
is a fine answer.
Short version: embedding
Engineperdocs/INTEGRATION.md, there's nopublic way to hand it a host-declared tool. We had a reach-in
(
session.coordinator.mount("tools", ...)) that worked -- it's the sameshape
amplifier_agent_http/_session_runner.pyalready uses internally forHostToolProxy-- but we deleted it on principle: your internals aren't ourcontract. This proposes making the equivalent capability public at the
Engine/prepare layer, in the same shape as the existinginject_provider/inject_routing_matrixfunctions.We already see
docs_v1/05-interface/tools.md'sToolsConfig(host_tools=[HostTool(...)])covers exactly this for the
create_agentfacade, and we intend to move ontoit the moment it ships as code -- this is scoped only to the gap between now
and then.
No urgency implied; closing as "wait for v1" is a completely acceptable
outcome.