---
name: majiayu000/atomic-agents-agent-configuration
source: https://app.decimal.ai/s/majiayu000-atomic-agents-agent-configuration@1/SKILL.md
source_sha256: 246fbc5b1936
---

# Atomic Agents Agent Configuration

The `AtomicAgent` is the core class for LLM interactions in the Atomic Agents framework. It handles structured input/output, conversation history, and system prompt management.

## Basic Agent Setup

```python
import instructor
import openai
from atomic_agents.agents.base_agent import AtomicAgent, AgentConfig
from atomic_agents.lib.components.system_prompt_generator import SystemPromptGenerator
from atomic_agents.lib.components.chat_history import ChatHistory

# 1. Create instructor-wrapped client
client = instructor.from_openai(openai.OpenAI())

# 2. Configure the agent
config = AgentConfig(
    client=client,
    model="gpt-4o-mini",
    history=ChatHistory(),
    system_prompt_generator=SystemPromptGenerator(
        background=["You are an expert assistant."],
        steps=["1. Analyze the input.", "2. Generate response."],
        output_instructions=["Be concise and helpful."],
    ),
)

# 3. Create the agent with type parameters
agent = AtomicAgent[InputSchema, OutputSchema](config=config)
```

## AgentConfig Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `client` | Instructor client | Yes | Instructor-wrapped LLM client |
| `model` | str | Yes | Model identifier (e.g., "gpt-4o-mini") |
| `history` | ChatHistory | No | Conversation history manager |
| `system_prompt_generator` | SystemPromptGenerator | No | System prompt configuration |
| `input_schema` | BaseIOSchema | No | Override input schema |
| `output_schema` | BaseIOSchema | No | Override output schema |
| `model_api_parameters` | dict | No | Additional API parameters |

## LLM Provider Setup

### OpenAI
```python
import instructor
import openai

client = instructor.from_openai(openai.OpenAI(api_key=os.getenv("OPENAI_API_KEY")))
model = "gpt-4o-mini"  # or "gpt-4o", "gpt-4-turbo"
```

### Anthropic
```python
import instructor
import anthropic

client = instructor.from_anthropic(anthropic.Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY")))
model = "claude-sonnet-4-20250514"
```

### Groq
```python
import instructor
from groq import Groq

client = instructor.from_groq(Groq(api_key=os.getenv("GROQ_API_KEY")), mode=instructor.Mode.JSON)
model = "llama-3.1-70b-versatile"
```

### Ollama (Local)
```python
import instructor
import openai

client = instructor.from_openai(
    openai.OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
)
model = "llama3.1"
```

## Agent Execution Methods

### Synchronous
```python
output = agent.run(InputSchema(message="Hello"))
```

### Asynchronous
```python
output = await agent.run_async(InputSchema(message="Hello"))
```

### Streaming (Sync)
```python
for partial in agent.run_stream(InputSchema(message="Hello")):
    print(partial)  # Partial responses as they arrive
```

### Streaming (Async)
```python
async for partial in agent.run_async_stream(InputSchema(message="Hello")):
    print(partial)
```

## ChatHistory Management

```python
from atomic_agents.lib.components.chat_history import ChatHistory

# Create history
history = ChatHistory()

# Use with agent
config = AgentConfig(client=client, model=model, history=history)
agent = AtomicAgent[InputSchema, OutputSchema](config=config)

# Run multiple turns (history accumulates)
agent.run(InputSchema(message="Hello"))
agent.run(InputSchema(message="Tell me more"))

# Reset history
agent.reset_history()

# Save/load history
history_data = history.to_dict()
new_history = ChatHistory.from_dict(history_data)
```

## Context Providers

Dynamic context injection into system prompts:

```python
from atomic_agents.lib.components.system_prompt_generator import BaseDynamicContextProvider

class UserContextProvider(BaseDynamicContextProvider):
    def __init__(self):
        super().__init__(title="User Context")
        self.user_name = ""

    def get_info(self) -> str:
        return f"Current user: {self.user_name}"

# Register with agent
provider = UserContextProvider()
agent.register_context_provider("user", provider)

# Update context dynamically
provider.user_name = "Alice"
agent.run(input_data)  # System prompt now includes user context
```

## Token Counting

```python
# Get token usage
token_info = agent.get_context_token_count()

print(f"Total: {token_info.total}")
print(f"System prompt: {token_info.system_prompt}")
print(f"History: {token_info.history}")
print(f"Utilization: {token_info.utilization:.1%}")
```

## Hooks for Monitoring

```python
def on_response(response):
    print(f"Got response: {response}")

def on_error(error):
    print(f"Error: {error}")

agent.register_hook("completion:response", on_response)
agent.register_hook("completion:error", on_error)
agent.register_hook("parse:error", on_error)
```

Hook events:
- `completion:kwargs` - Before API call
- `completion:response` - After successful response
- `completion:error` - On API error
- `parse:error` - On parsing/validation error

## Model API Parameters

Pass additional parameters to the LLM:

```python
config = AgentConfig(
    client=client,
    model="gpt-4o",
    model_api_parameters={
        "max_tokens": 1000,
        "temperature": 0.7,
        "top_p": 0.9,
    },
)
```

## Best Practices

1. **Always wrap with instructor** - Required for structured outputs
2. **Use environment variables** - Never hardcode API keys
3. **Initialize history when needed** - Only if conversation state matters
4. **Type your agents** - `AtomicAgent[Input, Output]` for type safety
5. **Use streaming for long responses** - Better user experience
6. **Monitor with hooks** - Track errors and performance
7. **Reset history appropriately** - Prevent context overflow

## References

See `references/` for:
- `multi-provider.md` - Detailed provider configurations
- `async-patterns.md` - Async and streaming patterns

See `examples/` for:
- `basic-agent.py` - Minimal agent setup
- `streaming-agent.py` - Streaming implementation