Skip to main content
Orca Engine aggregates every tool your agent can invoke and exposes them through AgentContext. Use the context API to request the latest tool list on each invocation:
from orca.functions.agent_context import AgentContext

available_tools = AgentContext.current().get_tools()

Tool discovery overview

AgentContext.current().get_tools() returns an ordered list of tool definitions ready for use by your agent framework. The runtime combines two sources:
  • Static tools that you register with your agent package or configure through deployment metadata.
  • Managed Model Context Protocol (MCP) tools supplied by the StreamNative cloud console and connected MCP servers.
Tool entries with duplicate names are skipped automatically so the first matching definition wins. When your organization scopes tools through inclusion rules, only allowed entries appear in the final list.

Use tools in agent code

Invoke get_tools() inside the handler that constructs your agent rather than caching results at import time. This ensures each invocation sees the current configuration and any MCP updates.
from agents import Agent, function_tool
from orca.functions.agent_context import AgentContext

@function_tool
async def fetch_weather(city: str) -> str:
    return "Weather data goes here"

managed_tools = AgentContext.current().get_tools()

root_agent = Agent(
    name="operations_assistant",
    instructions="Use managed tools whenever additional context is helpful.",
    tools=[fetch_weather, *managed_tools],
)
Agents built with other frameworks follow the same pattern: request the active context, append your static helpers, and pass the combined list to the runtime.

Dynamic updates with the model context protocol

Orca Engine maintains long-lived Server-Sent Events (SSE) streams to each registered MCP server. These notifications power two capabilities:
  • Dynamic tool discovery: When an MCP server adds, removes, or updates a tool, the runtime refreshes its catalog and the next call to get_tools() reflects the change—no redeployment required.
  • Real-time MCP messages: SSE messages surface remote events so your agent can react to live signals, such as tool hot reloads or targeted prompts from connected systems.
When the runtime receives a “tools changed” notification and detects a difference from the cached definition set, it reloads the active agent instance before processing additional requests. This refresh ensures subsequent calls to get_tools() return the latest tools and that long-lived sessions see the updated capabilities. Because MCP updates arrive asynchronously, call get_tools() within the request scope or immediately before you instantiate the agent. Avoid storing the returned list in module-level variables.

Best practices

  • Request AgentContext.current().get_tools() inside the invocation flow to pick up runtime changes.
  • Use descriptive names and function comments for static tools so large-language-model-based agents can choose them accurately.
  • Coordinate session strategy with your tooling approach—combine this page with Agent Context for state, metrics, and session controls.
  • When testing locally, inject a mock context that provides representative tool lists before importing modules that expect runtime tools.
With these patterns, your Orca Engine agents can blend built-in helpers with dynamically managed MCP integrations while staying up to date automatically.
I