feat: add AgentAsTool internal class

[notowen333]

Description

Adding an asTool method to the Agent class, matching what was released to python: https://github.com/strands-agents/sdk-python/blob/main/src/strands/agent/_agent_as_tool.py

The feature that this implementation is missing is Interrupts because this is a gap in the sdk-typescript.

Otherwise this implementation closely follows python and handles streaming, ToolResults, and preserve context in the same way. This implementation is able to take advantage of snapshots which are not available in python.

This PR also adds the sugar we have in python to automatically convert agents in the tools array.

Motivation

Multi-agent orchestration requires a parent agent to delegate subtasks to specialized child agents. Until now, there was no built-in way to use one Agent as a tool within another agent's tool set — users had to manually invoke sub-agents inside custom tool callbacks and marshal results themselves.

This PR introduces Agent.asTool() and automatic agent wrapping in the tools array, making agent delegation a first-class pattern.

Public API Changes

Agent.asTool(options?) — wraps an agent as a tool for use by another agent:

const researcher = new Agent({
  name: 'researcher',
  description: 'Finds information on a topic',
  printer: false,
})

// Explicit wrapping with options
const tool = researcher.asTool({ preserveContext: true })

// Pass agents directly in tools array (auto-wrapped)
const orchestrator = new Agent({
  tools: [researcher],
})

preserveContext controls whether the sub-agent retains conversation history across invocations:

• false (default) — resets messages, state, and system prompt before each call using the session snapshot preset
• true — accumulates context across calls, useful for agents that need memory of prior interactions

A SessionManager on the sub-agent is incompatible with preserveContext: false and will throw at construction time.

Agent.sessionManager — the agent now exposes its SessionManager as a public readonly property (detected from either the sessionManager or plugins config fields).

Use Cases

Specialized delegation — a writer agent delegates research to a researcher agent, each with their own tools and system prompts:

const researcher = new Agent({ name: 'researcher', tools: [searchTool], printer: false })
const writer = new Agent({ name: 'writer', tools: [researcher] })
await writer.invoke('Write an article about quantum computing')

Stateful sub-agents — a sub-agent that builds context over multiple calls:

const analyst = new Agent({ name: 'analyst', printer: false })
const manager = new Agent({
  tools: [analyst.asTool({ preserveContext: true })],
})

Related Issues

#765

Documentation PR

Will follow up once merged to generate valid snippets.

Type of Change

New feature

Testing

Added unit tests and an integration test.

• I ran npm run check

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[github-actions]

API Review Required

This PR introduces new public API surface:

• Agent.asTool() method
• AgentAsToolOptions type export
• Agent instances accepted in ToolList

Per the API Bar Raising guidelines, this requires API review before merge. Please:

1. Add the needs-api-review label
2. Update the PR description to include:
   • Complete API signatures with default parameter values
   • Module exports (what's exported from each module)
   • End-to-end example usage from the customer's perspective

[github-actions]

Documentation PR Required

This PR adds new public API surface (Agent.asTool(), AgentAsToolOptions, auto-wrapping of agents in tools array). Per review guidelines, a documentation PR is required for new features that add public API.

The PR description mentions "Will follow up once merged to generate valid snippets" - however, documentation should be prepared alongside the feature. Please provide a link to the documentation PR or explain why documentation is not needed before merging.

[github-actions]

Review Summary

Assessment: Request Changes

This is a well-implemented feature that brings Python SDK parity for the agent-as-tool pattern. The code is clean, well-documented, and comprehensively tested. However, there are a few items that need to be addressed before merging.

Review Categories

• API Review: New public API surface requires API bar raising review per team guidelines
• Documentation: Documentation PR required for new public APIs before merge
• Validation: Session manager + preserveContext=false conflict not validated (Python SDK does this)

The implementation follows the Python SDK patterns well and the streaming/snapshot approach is solid.

[github-actions]

Updated Review

Assessment: Request Changes → pending process items

Thanks for addressing the session manager validation! The implementation is solid with comprehensive test coverage.

✅ Resolved

• Session manager + preserveContext=false conflict is now properly validated
• New hasPluginOfType method is a clean approach

⚠️ Still Pending

API Review: This PR now includes additional public API surface:

• Agent.asTool() method
• AgentAsToolOptions type export
• Agent instances in ToolList
• Agent.hasPluginOfType() method (new)
• PluginRegistry.hasPluginOfType() method (new)

Please add the needs-api-review label per API Bar Raising guidelines.

Documentation PR: The description still mentions "Will follow up once merged" - documentation should be prepared alongside the feature for new public APIs.

[zastrowm]

I'm focusing on api review; someone else should review implementation

[github-actions]

Final Review

Assessment: Approve (pending API review completion)

The implementation has been refined and the PR description now provides comprehensive API documentation.

✅ Implementation Quality

• Cleaner design: Agent.sessionManager property is simpler than the previous hasPluginOfType approach
• Proper snapshot preset: Using { preset: 'session' } for state reset
• Comprehensive tests: All validation scenarios covered
• Good error messages: Clear guidance when SessionManager conflicts with preserveContext=false

✅ PR Description

The updated description now includes:

• Motivation and use cases
• Complete API signatures with defaults
• Code examples from customer perspective

Public API Surface

API	Description
Agent.asTool(options?)	Wraps agent as tool for another agent
AgentAsToolOptions	Type export for options
Agent in ToolList	Auto-wrapped when passed in tools array
Agent.sessionManager	Readonly property exposing session manager

The code is well-structured and follows Python SDK patterns. Ready for merge once API review by @zastrowm is complete.