Skip to main content

Agent

The Agent class is the heart of openstackai's agent framework.

Basic Usage​

from openstackai import Agent, Runner

agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant."
)

result = Runner.run_sync(agent, "Hello, how are you?")
print(result.final_output)

Constructor Parameters​

ParameterTypeDescription
namestrAgent identifier
instructionsstrSystem prompt / persona
toolslistFunctions the agent can call
handoffslist[Agent]Agents to transfer to
llmLLMProviderLLM provider instance
memoryMemoryMemory system
memory_typestr"conversation" or "vector"
configAgentConfigAdvanced configuration

With Tools​

from openstackai import Agent, Runner
from openstackai.skills import tool

@tool(description="Search the web")
async def search(query: str) -> str:
    return f"Results for: {query}"

@tool(description="Get weather")
async def get_weather(city: str) -> str:
    return f"Weather in {city}: Sunny, 72°F"

agent = Agent(
    name="ResearchBot",
    instructions="Help users find information.",
    tools=[search, get_weather]
)

result = Runner.run_sync(agent, "What's the weather in NYC?")

With Handoffs​

from openstackai import Agent, Runner

# Specialist agents
billing = Agent(name="Billing", instructions="Handle billing questions")
technical = Agent(name="Technical", instructions="Handle technical issues")
sales = Agent(name="Sales", instructions="Handle sales inquiries")

# Router agent
router = Agent(
    name="Router",
    instructions="Route to appropriate specialist",
    handoffs=[billing, technical, sales]
)

result = Runner.run_sync(router, "I have a question about my invoice")
# Automatically routes to billing agent

With LLM Provider​

OpenAI​

from openstackai import Agent
from openstackai.core import OpenAIProvider, LLMConfig

provider = OpenAIProvider(LLMConfig(
    api_key="sk-...",
    model="gpt-4o-mini"
))

agent = Agent(name="Bot", instructions="...", llm=provider)

Azure OpenAI​

from openstackai.core import AzureOpenAIProvider, LLMConfig

# With API Key
provider = AzureOpenAIProvider(LLMConfig(
    api_key="your-key",
    api_base="https://your-resource.openai.azure.com/",
    model="gpt-4o-mini"
))

# With Azure AD (no API key needed!)
provider = AzureOpenAIProvider(LLMConfig(
    api_base="https://your-resource.openai.azure.com/",
    model="gpt-4o-mini"
    # Uses DefaultAzureCredential automatically
))

agent = Agent(name="Bot", instructions="...", llm=provider)

Anthropic​

from openstackai.core import AnthropicProvider, LLMConfig

provider = AnthropicProvider(LLMConfig(
    api_key="sk-ant-...",
    model="claude-3-sonnet"
))

Ollama (Local)​

from openstackai.core import OllamaProvider, LLMConfig

provider = OllamaProvider(LLMConfig(
    api_base="http://localhost:11434",
    model="llama2"
))

With Memory​

Conversation Memory​

from openstackai import Agent
from openstackai.core import ConversationMemory

memory = ConversationMemory(max_messages=50)

agent = Agent(
    name="Bot",
    instructions="...",
    memory=memory
)

# Or use shorthand
agent = Agent(
    name="Bot",
    instructions="...",
    memory_type="conversation"
)

Vector Memory​

from openstackai.core import VectorMemory

memory = VectorMemory(provider="chromadb")

agent = Agent(
    name="Bot",
    instructions="...",
    memory=memory
)

Advanced Configuration​

from openstackai import Agent
from openstackai.core import AgentConfig

config = AgentConfig(
    max_iterations=10,
    timeout=60,
    retry_count=3,
    retry_delay=1.0,
    temperature=0.7,
    max_tokens=4096,
)

agent = Agent(
    name="Bot",
    instructions="...",
    config=config
)

Agent Response​

The Runner returns a RunResult:

result = Runner.run_sync(agent, "Hello")

result.status           # RunStatus.COMPLETED
result.final_output     # The final text response
result.messages         # Full conversation history
result.tool_calls       # Tools that were called
result.metadata         # Additional info (tokens, timing)

Running Agents​

Synchronous​

result = Runner.run_sync(agent, "Hello")

Asynchronous​

result = await Runner.run_async(agent, "Hello")

Streaming​

from openstackai.runner import StreamingRunner

async for event in StreamingRunner.stream(agent, "Hello"):
    if event.type == "token":
        print(event.data, end="", flush=True)

Next Steps​

  • [[Runner]] - Execution patterns in detail
  • [[Creating Tools]] - Build custom tools
  • [[Handoffs]] - Agent-to-agent transfers
  • [[Memory]] - Memory systems