agentintent 0.1.0
Trust infrastructure for AI agents - AI should do what it says, we make sure it does
Requires Python: >=3.9
Keywords: ai, agents, llm, trust, monitoring, observability, langchain, crewai, autogen

# AgentIntent

**AI Should Do What It Says. We Make Sure It Does.**

AgentIntent is the trust infrastructure for AI agents. Register your agents, declare their intent, and monitor their behavior to build trust.

## Installation

```bash
pip install agentintent
```

With LangChain support:
```bash
pip install agentintent[langchain]
```

## Quick Start

### LangChain (2 lines of code)

```python
from langchain.agents import AgentExecutor
from agentintent import AgentIntentCallback

# Just add our callback - that's it!
agent = AgentExecutor(
    agent=my_agent,
    tools=my_tools,
    callbacks=[AgentIntentCallback("ai_xxxxx")]  # ← Add this line
)

# Use your agent as normal
result = agent.invoke({"input": "Do something"})
```

### With Intent Manifest (recommended)

Define what your agent should do, and we'll make sure it does:

```python
from agentintent import AgentIntent, IntentManifest

# Define what your agent is supposed to do
manifest = IntentManifest(
    name="ExpenseBot",
    description="Processes expense reports",
    
    # Tools this agent is allowed to use
    allowed_tools=["email_read", "ocr", "form_submit"],
    
    # Tools this agent must NEVER use
    forbidden_tools=["code_execute", "file_delete", "send_email"],
    
    # Block violations instead of just warning
    enforcement_mode="block"
)

# Initialize AgentIntent
ai = AgentIntent(api_key="ai_xxxxx", manifest=manifest)

# Get the callback for LangChain
callback = ai.langchain_callback()

# Use with your agent
agent = AgentExecutor(
    agent=my_agent,
    tools=my_tools,
    callbacks=[callback]
)

# If agent tries to use a forbidden tool, it will be blocked
result = agent.invoke({"input": "Process this expense report"})
```

### Universal Wrapper (any framework)

```python
from agentintent import monitor

# Wrap any agent or function
monitored_agent = monitor(your_agent, api_key="ai_xxxxx")

# Or use as a decorator
@monitor(api_key="ai_xxxxx")
def my_agent_function(input):
    # Your agent logic
    return result
```

## Features

### 🛡️ Intent Declaration

Tell us what your agent should do:

```python
manifest = IntentManifest(
    name="CustomerServiceBot",
    allowed_tools=["search_kb", "send_response"],
    forbidden_tools=["access_billing", "modify_account"],
    allowed_api_patterns=["api.company.com/*"],
    forbidden_api_patterns=["*.stripe.com/*"],
)
```

### 📊 Automatic Monitoring

Every action is tracked:
- LLM calls (model, tokens, duration)
- Tool usage (which tools, inputs/outputs)
- API calls (endpoints, patterns)
- Agent decisions (reasoning, tool selection)

### ⚡ Real-Time Enforcement

Block bad behavior before it happens:

```python
# enforcement_mode options:
# - "block": Raise exception on violation
# - "warn": Log warning but allow
# - "log": Just log, no warnings

manifest = IntentManifest(
    name="SecureBot",
    forbidden_tools=["dangerous_tool"],
    enforcement_mode="block"  # Will raise EnforcementError
)
```

### 🏆 Trust Score

Build reputation over time:

```python
# Get your agent's trust score
score = ai.get_trust_score()
# {
#     "score": 94,
#     "tier": "TRUSTED",
#     "breakdown": {
#         "intent_alignment": 98,
#         "behavioral_consistency": 96,
#         "developer_reputation": 91,
#         "security_posture": 89
#     }
# }
```

## Supported Frameworks

| Framework | Status | Integration |
|-----------|--------|-------------|
| LangChain | ✅ Ready | Callback handler |
| CrewAI | 🚧 Coming | Agent wrapper |
| AutoGen | 🚧 Coming | Message interceptor |
| LlamaIndex | 🚧 Coming | Event handler |
| Custom Python | ✅ Ready | Decorator/wrapper |

## Performance

AgentIntent is designed for zero-impact monitoring:

- **< 1ms overhead** per action (local enforcement)
- **Async logging** (never blocks your agent)
- **Batched uploads** (efficient network usage)
- **Fail-safe** (if our cloud is down, your agent keeps running)

## Configuration

### Environment Variables

```bash
export AGENTINTENT_API_KEY="ai_xxxxx"
export AGENTINTENT_BASE_URL="https://api.agentintent.ai/v1"  # optional
```

### Manifest from File

```python
# manifest.yaml
manifest = IntentManifest.from_file("manifest.yaml")
```

```yaml
# manifest.yaml
name: MyAgent
version: "1.0.0"
description: Does useful things

allowed_tools:
  - search
  - calculator

forbidden_tools:
  - code_execute
  - file_delete

limits:
  max_llm_calls_per_minute: 60
  max_tool_calls_per_minute: 120

enforcement_mode: warn
```

## API Reference

### AgentIntent

```python
ai = AgentIntent(
    api_key="ai_xxxxx",
    manifest=manifest,           # Optional: IntentManifest
    enforcement_mode="warn",     # Optional: override manifest
    cloud_enabled=True,          # Optional: disable cloud logging
)

# Get callbacks/wrappers
callback = ai.langchain_callback()

# Manual logging
ai.log_action("tool_call", {"tool": "search", "query": "..."})

# Check enforcement
result = ai.check_tool("dangerous_tool")
if result.blocked:
    print(f"Blocked: {result.reason}")

# Get metrics
metrics = ai.get_metrics()

# Cleanup
ai.close()
```

### IntentManifest

```python
manifest = IntentManifest(
    name="MyAgent",
    version="1.0.0",
    description="What this agent does",
    
    # Tool permissions
    allowed_tools=["tool1", "tool2"],
    forbidden_tools=["bad_tool"],
    
    # API permissions (regex patterns)
    allowed_api_patterns=["api.safe.com/*"],
    forbidden_api_patterns=["*.dangerous.com/*"],
    
    # Data permissions
    allowed_data_sources=["public_db"],
    forbidden_data_sources=["private_db", "credentials"],
    
    # Rate limits
    limits={
        "max_llm_calls_per_minute": 60,
        "max_tool_calls_per_minute": 120,
    },
    
    # Enforcement
    enforcement_mode="block",  # or "warn" or "log"
)
```

## License

MIT License - see the LICENSE file in the repository.

## Links

- Website: https://agentintent.ai
- Documentation: https://docs.agentintent.ai
- GitHub: https://github.com/agentintent/agentintent-python
- Discord: https://discord.gg/agentintent