Agenticx Agent Builder

AgenticX Agent Builder

Guide for creating production-grade agents in AgenticX.

Core Concepts

An Agent in AgenticX consists of:

• Identity: id, name, role, goal
• LLM Provider: the language model backend
• Tools: functions the agent can invoke
• Executor: the runtime that orchestrates agent reasoning

Creating an Agent

Minimal Agent

from agenticx import Agent, Task, AgentExecutor
from agenticx.llms import OpenAIProvider

agent = Agent(
    id="assistant",
    name="Assistant",
    role="General Purpose Assistant",
    goal="Help users with tasks",
    organization_id="default"
)

Agent with Rich Configuration

agent = Agent(
    id="research-analyst",
    name="Research Analyst",
    role="Senior Research Analyst",
    goal="Produce thorough, well-cited research reports",
    backstory="10 years experience in data-driven research",
    organization_id="research-team",
    verbose=True
)

CLI Creation

agx agent create research-analyst --role "Senior Research Analyst"
agx agent list

LLM Providers

AgenticX supports multiple LLM backends through a unified interface:

from agenticx.llms import OpenAIProvider, LiteLLMProvider

# OpenAI
llm = OpenAIProvider(model="gpt-4")

# Any model via LiteLLM (Codex, Gemini, local models, etc.)
llm = LiteLLMProvider(model="anthropic/Codex-sonnet-4-20250514")
llm = LiteLLMProvider(model="ollama/llama3")

Adding Tools

Function Decorator Tools

from agenticx.tools import tool

@tool
def search_web(query: str) -> str:
    """Search the web for information."""
    return f"Results for: {query}"

@tool
def calculate(expression: str) -> float:
    """Evaluate a math expression safely."""
    return eval(expression)  # use ast.literal_eval in production

Attaching Tools to Execution

executor = AgentExecutor(
    agent=agent,
    llm=llm,
    tools=[search_web, calculate]
)
result = executor.run(task)

Task Definition

task = Task(
    id="research-task",
    description="Research the latest trends in AI agents",
    expected_output="A structured report with sections and citations",
    context={"domain": "artificial-intelligence"}
)

Output Validation

AgenticX validates task outputs using Pydantic:

from pydantic import BaseModel

class ResearchReport(BaseModel):
    title: str
    summary: str
    findings: list[str]

task = Task(
    id="validated-task",
    description="Research AI trends",
    expected_output="Structured research report",
    output_model=ResearchReport
)

Execution Strategies

Basic Execution

executor = AgentExecutor(agent=agent, llm=llm)
result = executor.run(task)

With Events & Callbacks

AgenticX emits events during execution (TaskStart, ToolCall, LLMCall, etc.):

from agenticx.core import EventLog

event_log = EventLog()
executor = AgentExecutor(agent=agent, llm=llm, event_log=event_log)
result = executor.run(task)

for event in event_log.events:
    print(f"{event.type}: {event.data}")

Multi-Agent Patterns

Agent Handoff

from agenticx.core import HandoffOutput

# Agent A can hand off to Agent B
handoff = HandoffOutput(target_agent="agent-b", context={"data": result})

Communication Interface

from agenticx.core import BroadcastCommunication

comm = BroadcastCommunication()
comm.send(sender="agent-a", message="Task complete", data=result)

GuideRails

Constrain agent behavior with guardrails:

from agenticx.core import GuideRails, GuideRailsConfig

config = GuideRailsConfig(
    max_iterations=10,
    timeout_seconds=60,
    abort_on_failure=True
)
guardrails = GuideRails(config=config)

Best Practices

1. Specific roles — narrow roles produce better results than generic ones
2. Clear goals — state what success looks like
3. Minimal tools — only attach tools the agent actually needs
4. Output validation — use Pydantic models for structured outputs
5. Event logging — always enable for debugging and monitoring