Skip to content

Defining Agents

from astromesh_adk import agent
@agent(name="assistant", model="openai/gpt-4o", description="General assistant")
async def assistant(ctx):
"""You are a helpful assistant."""
return None # Use default orchestration

The docstring becomes the system prompt. Return None to run the agent’s orchestration pattern, or return a string to answer directly without calling the model. (ctx.run_default() is not wired by the runner and raises.)

from astromesh_adk import Agent, RunContext
class MyAgent(Agent):
"""You are a planning assistant."""
name = "custom"
model = "ollama/llama3"
pattern = "plan_and_execute"
async def on_before_run(self, ctx: RunContext):
"""Called before execution."""
async def on_after_run(self, ctx: RunContext, result):
"""Called after execution."""

The class docstring is the system prompt. on_before_run and on_after_run are called by the runner; system_prompt_fn and on_tool_call exist on the base class but the runner does not call them yet.

ParameterTypeDescription
namestrAgent identifier
modelstrProvider/model (e.g., "openai/gpt-4o")
descriptionstrShown when the agent is used as a tool. Defaults to name
toolslistTools available to the agent
patternstrOrchestration: react (default), plan_and_execute, parallel_fan_out, pipeline. An unknown value raises AgentConfigError when the agent is defined. supervisor also works for a single agent (its workers are tools made with other_agent.as_tool()); swarm and parallel are team patterns
stageslist[str]Stage names for pattern="pipeline"
max_iterationsintOrchestration iteration cap. Default 10
memorystr | dictConversational memory, built by the core factory — only redis is supported, with its URL: {"conversational": {"backend": "redis", "connection": {"url": "redis://..."}}} and the core redis extra. Any other backend makes the run raise
guardrailsdictInput/output guardrails, enforced locally
rolesdict[str, str]Model per pattern role (reasoner, planner, worker, synthesizer, supervisor, stage:<name>); roles not listed use model
max_tool_result_tokensintCap on each tool result entering the model (default 8000, as in the core); @tool(max_result_tokens=N) overrides it per tool
context_windowintWith memory, the history is trimmed to a budget of 90% of the window minus prompt, tools and answer. Without it the litellm window is used when known; if not, no trimming
fallback_modelstrFallback provider/model
routingstrRouting strategy. Default cost_optimized
model_configdictExtra model parameters

guardrails= runs on the core’s GuardrailsEngine, as in a node: input rules before memory and the model, output rules on the answer and the steps, and cost_limit before each model call. The short form ["pii_detection"] expands to {"type": "pii_detection"} and the core sets the default action.

A block is a result, not an error. RunResult.blocked is True, answer is the rejection message and guardrail says {direction, rule, reason}. A blocked input does not enter the history. Teams: the guardrails of the supervisor (or entry) agent apply.

result = await my_agent.run("...")
if result.blocked:
print(result.guardrail["rule"], result.guardrail["reason"])

RunResult also carries propuestas (writes a mode: propose tool recorded without executing) and by_model (the core’s usage.by_model, with tokens_cached). Remote runs copy them from the node’s response.

@agent(name="analyst", model="openai/gpt-4o-mini",
roles={"planner": "openai/gpt-4o", "synthesizer": "openai/gpt-4o"},
pattern="plan_and_execute")
async def analyst(ctx): """..."""
Built by FAiNANSU