# 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

```python
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**

```python
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

```python
# 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

```json
{
  "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"}
      }
    }
  ]
}
```

{% hint style="warning" %}
**Security Warning**: Never commit secrets in JSON configuration files. Use environment variables or your secret manager. See **Security** for best practices.
{% endhint %}

## 🔄 Coordination Patterns

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

### Hierarchical Coordination

```python
# 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

````python
# 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:

```python
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:

````python
# 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:

```python
# 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!
