Core Concepts

Understanding the fundamental concepts behind the AIP SDK will help you build better AI applications.

🎯 At a Glance

  • 🤖 Agents: AI entities with instructions, tools, and models

  • 🛠️ Tools: Extend agent capabilities with custom functions

  • 🔌 MCPs: Connect to external services and APIs

  • 🧠 Models: Language models with configurable parameters

  • 💬 Sessions: Context maintained within single runs

🤖 Agent Anatomy

An AI Agent is a software entity that can perceive its environment, make decisions, and take actions to achieve specific goals.

Agent Components

agent = client.create_agent(
    name="math-tutor",                    # Unique identifier
    instruction="You are a patient math tutor. Explain concepts clearly and use tools to solve problems.",  # Behavior guidelines
    tools=["calculator", "equation-solver"],  # Capabilities
    model="gpt-4"                         # Language model
)

  • Name: Unique identifier for the agent

  • Instruction: The agent's personality and behavior guidelines

  • Tools: Capabilities the agent can use

  • Model: The language model that powers the agent's reasoning

🧠 Models & Parameters

Choose a language model per agent (model), then tune behavior with parameters like temperature/top_p and max tokens. Prefer lower temperature for deterministic utilities; higher for creative tasks.

Model Selection Tips:

  • Deterministic tasks: Use lower temperature (0.1-0.3) for consistent results

  • Creative tasks: Use higher temperature (0.7-0.9) for varied outputs

  • Cost optimization: Balance model capability with your budget

  • Latency requirements: Consider response time needs

See Agents Guide → Model Selection for provider-specific details.

TODO: Add model selection diagram showing latency/cost/quality triangle

🛠️ Tools: Extending Agent Capabilities

For detailed tool creation and management, see Tools Guide.

Tools are functions that agents can call to perform specific tasks. They're like the agent's "hands" - allowing it to interact with the world beyond just conversation.

Types of Tools

Custom Tools

from gllm_plugin.tools import tool_plugin
from langchain_core.tools import BaseTool

@tool_plugin(version="1.0.0")
class AreaCalculator(BaseTool):
    name = "area_calculator"
    description = "Calculate the area of geometric shapes."
    
    def _run(self, shape: str, **dimensions) -> str:
        """Calculate area based on shape and dimensions."""
        if shape == "circle":
            radius = dimensions.get("radius", 0)
            area = 3.14159 * radius ** 2
            return f"Area of circle with radius {radius}: {area:.2f}"
        elif shape == "rectangle":
            length = dimensions.get("length", 0)
            width = dimensions.get("width", 0)
            area = length * width
            return f"Area of rectangle {length}x{width}: {area}"
        else:
            return f"Unknown shape: {shape}"

Tool Sources

  • SDK Tools: Custom Python classes with @tool_plugin decorator

  • MCP Tools: External services and APIs via Model Context Protocol

  • Framework Tools: LangChain and other AI framework integrations

Tool Integration

# Create a tool
calculator_tool = client.create_tool(
    name="area-calculator",
    file_path="area_calculator.py",
    framework="langchain",
    description="Calculate areas of geometric shapes"
)

# Give it to an agent
agent = client.create_agent(
    name="geometry-helper",
    instruction="Help with geometry problems using the area calculator.",
    tools=[calculator_tool]
)

🔌 MCP: Connecting to External Services

For detailed MCP setup and management, see MCPs Guide.

Model Context Protocol (MCP) is a standard way for AI agents to connect to external services and tools. Think of it as a universal adapter for different APIs and services.

MCP Benefits

  • Standardized Interface: Consistent way to connect to any service

  • Tool Discovery: Agents can automatically discover available tools

  • Secure Access: Controlled access to external resources

  • Extensibility: Easy to add new services and capabilities

Example MCP Configuration

{
  "url": "https://api.weather-service.com",
  "auth_token": "your-token",
  "transport": "http",
  "tools": [
    {
      "name": "get_weather",
      "description": "Get current weather for a location",
      "parameters": {
        "location": {"type": "string", "required": true},
        "units": {"type": "string", "default": "metric"}
      }
    }
  ]
}

Security Warning: Never commit secrets in JSON configuration files. Use environment variables or your secret manager. See Security for best practices.

🔄 Coordination Patterns

Agents can work together, creating sophisticated multi-agent systems where each agent has specialized expertise.

Hierarchical Coordination

# Create specialized agents
researcher = client.create_agent(
    name="researcher",
    instruction="Research topics thoroughly and provide detailed information."
)

writer = client.create_agent(
    name="writer",
    instruction="Write clear, engaging content based on research."
)

# Create coordinator
coordinator = client.create_agent(
    name="content-creator",
    instruction="Coordinate research and writing to create content.",
    agents=[researcher, writer]
)

TODO: Add execution lifecycle diagram showing agent run → tool calls → events → result

Peer-to-Peer Collaboration

# Agents that can call each other
math_agent = client.create_agent(
    name="math-specialist",
    instruction="Solve mathematical problems.",
    agents=[physics_agent]  # Can consult physics agent
)

physics_agent = client.create_agent(
    name="physics-specialist", 
    instruction="Solve physics problems.",
    agents=[math_agent]     # Can consult math agent
)

{% hint style="warning" %}
**Coordination Caution**: Be careful with circular references between agents. Set appropriate timeouts and permissions to prevent infinite loops and ensure proper error handling.
{% endhint %}

## 💬 Conversation Context

Agents can maintain context within a single conversation session, allowing for more natural and coherent interactions.

### Session Context

- **Chat History**: Previous messages and responses within the current session
- **Tool Usage**: What tools were used and their results in the current session
- **Agent State**: Current goals and progress within the session

### Context Usage

```python
# Agents can use chat history for context
agent = client.create_agent(
    name="conversational-assistant",
    instruction="Use conversation context to provide coherent responses."
)

# Context is maintained within the same run session
response = agent.run(
    "My name is Alice and I prefer metric units.",
    chat_history=[
        {"role": "user", "content": "Hello"},
        {"role": "assistant", "content": "Hi! How can I help you today?"}
    ]
)

Note: Unspecified parameters use platform defaults. You can override specific settings:

agent = client.create_agent(
    name="deterministic",
    instruction="Be precise.",
    model="gpt-4",
    agent_config={
        "lm_provider": "openai",
        "lm_name": "gpt-4",
        "lm_hyperparameters": {
            "temperature": 0.2,  # Set temperature via agent_config
            "max_tokens": 1000
        }
    }
)

Important: To set hyperparameters like temperature, max_tokens, etc., you must use the agent_config format shown above. Direct parameters like temperature=0.2 are not supported and will be ignored.

Sessions vs Runs vs Persistence

  • Run: A single agent execution with input and output

  • Session: Context maintained within one run (chat history, tool usage)

  • Persistence: Long-term memory across multiple runs (implement your own storage)

For live reasoning steps and event streams, see Streaming & Renderers.

TODO: Add context boundaries diagram showing what persists vs what doesn't

🎯 Agent Design Patterns

Single Responsibility

Each agent should have one clear purpose:

# Good: Focused agent
calculator_agent = client.create_agent(
    name="calculator",
    instruction="You are a math calculator. Provide accurate calculations only."
)

# Avoid: Overly broad agent
general_agent = client.create_agent(
    name="general",
    instruction="You can do everything: math, writing, analysis, cooking..."  # Too broad!
)

# Avoid: Too many tools attached
overloaded_agent = client.create_agent(
    name="overloaded",
    instruction="Use tools when needed",
    tools=[tool1, tool2, tool3, tool4, tool5, tool6, tool7, tool8]  # Too many!
)

### **Tool Composition**
Combine simple tools to create complex capabilities:

```python
# Simple, focused tools
data_fetcher = client.create_tool(name="data-fetcher", ...)
data_analyzer = client.create_tool(name="data-analyzer", ...)
data_visualizer = client.create_tool(name="data-visualizer", ...)

# Complex agent that composes them
data_scientist = client.create_agent(
    name="data-scientist",
    instruction="Analyze data by fetching, processing, and visualizing it.",
    tools=[data_fetcher, data_analyzer, data_visualizer]
)

Progressive Enhancement

Start simple and add complexity gradually:

# Phase 1: Basic agent
basic_agent = client.create_agent(
    name="basic-assistant",
    instruction="Provide helpful responses to user questions."
)

# Phase 2: Add tools
enhanced_agent = client.create_agent(
    name="enhanced-assistant",
    instruction="Provide helpful responses and use tools when needed.",
    tools=[calculator_tool]
)

# Phase 3: Add agent collaboration
coordinator = client.create_agent(
    name="coordinator",
    instruction="Coordinate between specialized agents.",
    agents=[basic_agent, enhanced_agent]
)

🔧 Best Practices

Agent Design

  • Clear Instructions: Write specific, actionable instructions

  • Appropriate Scope: Don't make agents do too many things

  • Tool Selection: Choose tools that match the agent's purpose

  • Error Handling: Design agents to handle failures gracefully

Tool Development

  • Single Purpose: Each tool should do one thing well

  • Clear Interface: Use descriptive parameter names and types

  • Error Handling: Provide helpful error messages

  • Documentation: Document what the tool does and how to use it

System Architecture

  • Modular Design: Build systems from reusable components

  • Clear Boundaries: Define how agents interact with each other

  • Scalability: Design for growth and change

  • Monitoring: Track agent performance and usage

🚀 Next Steps

  • Practice: Try building simple agents with the Quick Start Guide

  • Build Agents: Follow the Agents Guide

  • Create Tools: Learn to build custom tools

  • Connect Services: Integrate MCPs

Understanding these concepts will help you design better AI applications and make the most of the AIP SDK's capabilities!

PreviousConceptsNextTroubleshooting & FAQs