Injected State

Pass agent context into tools automatically without exposing it in the tool's public schema

Injected state lets tools receive hidden context — session ID, agent ID, previous results — without users or the LLM ever seeing those parameters in the tool schema.

from praisonaiagents import Agent, tool
from praisonaiagents.tools import Injected

@tool
def search(query: str, state=Injected()) -> str:
    """Search with hidden session context."""
    return f"Results for {query} (session={state.get(session_id)})"

agent = Agent(name="assistant", tools=[search])
agent.start("Find recent orders")

The user asks a question; hidden state is injected into the tool without appearing in the schema.

The LLM sees only query in the schema. The agent automatically fills state before calling the tool.

Quick Start

1. Simplest form — bare Injected

   from praisonaiagents import Agent, tool
   from praisonaiagents.tools import Injected
   
   @tool
   def quick_context(query: str, state: Injected) -> str:
       """Search with session context — bare Injected defaults to dict."""
       session = state.get("session_id", "unknown")
       return f"Results for '{query}' (session: {session})"
   
   agent = Agent(name="SearchBot", tools=[quick_context])
   agent.start("Find Python tutorials")

   Bare Injected behaves like Injected[dict] — excluded from the tool schema and resolved to state.to_dict().

2. Create a tool with injected state

   from praisonaiagents import Agent, tool
   from praisonaiagents.tools import Injected
   
   @tool
   def personalized_search(query: str, state: Injected[dict]) -> str:
       """Search with user context."""
       session = state.get("session_id", "unknown")
       return f"Results for '{query}' (session: {session})"
   
   agent = Agent(
       name="SearchBot",
       instructions="Search for information.",
       tools=[personalized_search]
   )
   
   result = agent.start("Find Python tutorials")

   The state parameter never appears in tool descriptions shown to the LLM — only query does.

3. Use AgentState for typed access

   from praisonaiagents import Agent, tool
   from praisonaiagents.tools import Injected
   from praisonaiagents.tools.injected import AgentState
   
   @tool
   def context_aware_tool(query: str, state: Injected[AgentState]) -> str:
       """Access typed agent state fields."""
       return (
           f"Query: {query}\n"
           f"Agent: {state.agent_id}\n"
           f"Session: {state.session_id}\n"
           f"Previous results: {len(state.previous_tool_results)}"
       )
   
   agent = Agent(
       name="ContextBot",
       instructions="Help with context-aware tasks.",
       tools=[context_aware_tool]
   )
   
   result = agent.start("What's the current context?")

How It Works

When a tool parameter is annotated with Injected, Injected[T], or bare Injected, the SDK:

1. Strips that parameter from the schema sent to the LLM
2. Captures the current AgentState at call time
3. Injects the state value automatically before the tool runs

Configuration Options

AgentState fields available at runtime:

Common Patterns

Multi-turn memory access in a tool:

from praisonaiagents import Agent, tool
from praisonaiagents.tools import Injected
from praisonaiagents.tools.injected import AgentState

@tool
def summarize_session(topic: str, state: Injected[AgentState]) -> str:
    """Summarize what we discussed about a topic this session."""
    history = state.previous_tool_results
    return f"Session {state.session_id} — {len(history)} tool calls so far on '{topic}'"

Testing with a manual injection context:

from praisonaiagents.tools.injected import AgentState, with_injection_context

state = AgentState(agent_id="test-agent", run_id="run-001", session_id="sess-42")

with with_injection_context(state):
    result = personalized_search(query="Python")
    print(result)

Validating the tool schema has no injected params:

import inspect
from praisonaiagents.tools import Injected

sig = inspect.signature(personalized_search)
public_params = [
    name for name, param in sig.parameters.items()
    if not (hasattr(param.annotation, "__origin__") and param.annotation.__origin__ is Injected)
]
print(public_params)

Best Practices

Related