> ## Documentation Index
> Fetch the complete documentation index at: https://docs.portkey.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Strands Agents

> Use Prisma AIRS AI Gateway with AWS's Strands Agents to take your AI Agents to production

Strands Agents is a simple-to-use agent framework built by AWS. The AI Gateway enhances Strands Agents with production-grade observability, reliability, and multi-provider support—all through a single integration that requires no changes to your existing agent logic.

**What you get with this integration:**

* **Complete observability** of every agent step, tool use, and LLM interaction
* **Built-in reliability** with automatic fallbacks, retries, and load balancing
* **3,000+ LLMs** accessible through the same OpenAI-compatible interface
* **Production monitoring** with traces, logs, and real-time metrics
* **Zero code changes** to your existing Strands agent implementations

<Card title="Strands Agents Documentation" href="https://strandsagents.com/">
  Learn more about Strands Agents' core concepts and features
</Card>

## Quick Start

<Steps>
  <Step title="Install Dependencies">
    ```bash theme={"system"}
    pip install -U strands-agents strands-agents-tools openai
    ```
  </Step>

  <Step title="Replace Your Model Initialization">
    Instead of initializing your OpenAI model directly:

    ```python theme={"system"}
    # Before: Direct OpenAI
    from strands.models.openai import OpenAIModel

    model = OpenAIModel(
        client_args={"api_key": "sk-..."},
        model_id="gpt-4o",
        params={"temperature": 0.7}
    )
    ```

    Initialize it through the AI Gateway:

    ```python theme={"system"}
    # After: Through the AI Gateway
    from strands.models.openai import OpenAIModel

    model = OpenAIModel(
        client_args={
            "api_key": "YOUR_PORTKEY_API_KEY",  # Your AI Gateway API key
            "base_url": "https://aigw.portkey.ai/v1"     # Routes through the AI Gateway
        },
        model_id="gpt-4o",
        params={"temperature": 0.7}
    )
    ```
  </Step>

  <Step title="Use Your Agent Normally">
    ```python theme={"system"}
    from strands import Agent
    from strands_tools import calculator

    agent = Agent(model=model, tools=[calculator])
    response = agent("What is 2+2?")
    print(response)
    ```

    Your agent works exactly the same way, but now all interactions are automatically logged, traced, and monitored in Strata Cloud Manager.
  </Step>
</Steps>

## How the Integration Works

The integration leverages Strands' flexible `client_args` parameter, which passes any arguments directly to the OpenAI client constructor. By setting `base_url` to the AI Gateway, all requests route through the AI Gateway while maintaining full compatibility with the OpenAI API.

```python theme={"system"}
# This is what happens under the hood in Strands:
client_args = client_args or {}
self.client = openai.OpenAI(**client_args)  # Your AI Gateway config gets passed here
```

This means you get all of the AI Gateway's features without any changes to your agent logic, tool usage, or response handling.

## Setting Up the AI Gateway

Before using the integration, you need to configure your AI providers and create an AI Gateway API key.

<Steps>
  <Step title="Add Your AI Provider Keys">
    Go to [Model Catalog](https://stratacloudmanager.paloaltonetworks.com/) in Strata Cloud Manager and add your AI provider keys (OpenAI, Anthropic, etc.). Each provider gets an AI Provider slug that you'll reference in configs.
  </Step>

  <Step title="Create a Configuration">
    Go to [Configs](https://stratacloudmanager.paloaltonetworks.com/) to define how requests should be routed. A basic config looks like:

    ```json theme={"system"}
    {
     "provider":"@openai-key-abc123"
    }
    ```

    For production setups, you can add fallbacks, load balancing, and conditional routing here.
  </Step>

  <Step title="Generate Your AI Gateway API Key">
    Go to [API Keys](https://stratacloudmanager.paloaltonetworks.com/) to create a new API key. Attach your config as the default routing config, and you'll get an API key that routes to your configured providers.
  </Step>
</Steps>

## Complete Integration Example

Here's a full example showing how to set up a Strands agent with AI Gateway integration:

```python [expandable] theme={"system"}
from strands import Agent
from strands.models.openai import OpenAIModel
from strands_tools import calculator, web_search

# Initialize model through the AI Gateway
model = OpenAIModel(
    client_args={
        "api_key": "YOUR_PORTKEY_API_KEY",
        "base_url": "https://aigw.portkey.ai/v1"
    },
    model_id="gpt-4o",
    params={
        "max_tokens": 1000,
        "temperature": 0.7,
    }
)

# Create agent with tools (unchanged from standard Strands usage)
agent = Agent(
    model=model,
    tools=[calculator, web_search]
)

# Use the agent (unchanged from standard Strands usage)
response = agent("Calculate the compound interest on $10,000 at 5% for 10 years, then search for current inflation rates")
print(response)
```

The agent will automatically use both tools as needed, and every step will be logged in Strata Cloud Manager with full request/response details, timing, and token usage.

## Production Features

### 1. Enhanced Observability

The AI Gateway provides comprehensive visibility into your agent's behavior without requiring any code changes.

<Tabs>
  <Tab title="Request Tracing">
    Track the complete execution flow of your agents with hierarchical traces that show:

    * **LLM calls**: Every request to language models with full payloads
    * **Tool invocations**: Which tools were called, with what parameters, and their responses
    * **Decision points**: How the agent chose between different tools or approaches
    * **Performance metrics**: Latency, token usage, and cost for each step

    ```python {11} theme={"system"}
    from strands import Agent
    from strands.models.openai import OpenAIModel
    from strands_tools import calculator

    model = OpenAIModel(
        client_args={
            "api_key": "YOUR_PORTKEY_API_KEY",
            "base_url": "https://aigw.portkey.ai/v1",
            # Add trace ID to group related requests
            "default_headers": {"x-portkey-trace-id": "user_session_123"}
        },
        model_id="gpt-4o",
        params={"temperature": 0.7}
    )

    agent = Agent(model=model, tools=[calculator])
    response = agent("What's 15% of 2,847?")
    ```

    All requests from this agent will be grouped under the same trace, making it easy to analyze the complete interaction flow.
  </Tab>

  <Tab title="Custom Metadata">
    Add business context to your agent runs for better filtering and analysis:

    This metadata appears in Strata Cloud Manager, allowing you to filter logs and analyze performance by user type, session, or any custom dimension.
  </Tab>

  <Tab title="Real-time Monitoring">
    Monitor your agents in production with built-in dashboards that track:

    * **Success rates**: Percentage of successful agent completions
    * **Average latency**: Response times across different agent types
    * **Token usage**: Track consumption and costs across models
    * **Error patterns**: Common failure modes and their frequency

    All metrics can be segmented by the metadata you provide, giving you insights like "premium user agents have 15% higher success rates" or "billing department queries take 2x longer on average."
  </Tab>
</Tabs>

### 2. Reliability & Fallbacks

When running agents in production, things can go wrong - API rate limits, network issues, or provider outages. The AI Gateway's reliability features ensure your agents keep running smoothly even when problems occur.

It's simple to enable fallback in your Strands Agents by using an AI Gateway Config that you can attach at runtime or directly to your AI Gateway API key. Here's an example of attaching a Config at runtime:

<Tabs>
  <Tab title="Automatic Fallbacks">
    Configure multiple providers so your agents keep working even when one provider fails:

    If OpenAI returns a rate limit error (429), the AI Gateway automatically retries the request with Anthropic's Claude, using default model mappings.
  </Tab>

  <Tab title="Load Balancing">
    Distribute requests across multiple API keys to stay within rate limits:

    Requests will be distributed 70/30 across your two OpenAI keys, helping you maximize throughput without hitting individual key limits.
  </Tab>

  <Tab title="Conditional Routing">
    Route requests to different providers/models based on custom logic (like metadata, input content, or user attributes) using the AI Gateway's Conditional Routing feature.

    See the [Conditional Routing documentation](/docs/aigw/product/ai-gateway/conditional-routing) for full guidance and advanced examples.
  </Tab>
</Tabs>

### 3. LLM Interoperability

Access 3,000+ models through the same Strands interface by changing just the provider configuration:

<Tabs>
  <Tab title="Using Multiple Providers in One Agent">
    ```python theme={"system"}
    # Create different model instances for different tasks
    reasoning_model = OpenAIModel(
        client_args={
            "api_key": "YOUR_PORTKEY_API_KEY",
            "base_url": "https://aigw.portkey.ai/v1",
            "default_headers": {"x-portkey-provider": "@openai-key"}
        },
        model_id="gpt-4o",
        params={"temperature": 0.1}  # Low temperature for reasoning
    )

    creative_model = OpenAIModel(
        client_args={
            "api_key": "YOUR_PORTKEY_API_KEY",
            "base_url": "https://aigw.portkey.ai/v1",
            "default_headers": {"x-portkey-provider": "@gemini-key"}
        },
        model_id="gemini-2.0-flash-exp",
        params={"temperature": 0.8}  # Higher temperature for creativity
    )

    # Use different models for different agent types
    reasoning_agent = Agent(model=reasoning_model, tools=[calculator])
    creative_agent = Agent(model=creative_model, tools=[])
    ```
  </Tab>
</Tabs>

The AI Gateway provides access to LLMs from providers including:

* OpenAI (GPT-4o, GPT-4 Turbo, etc.)
* Anthropic (Claude 3.5 Sonnet, Claude 3 Opus, etc.)
* Mistral AI (Mistral Large, Mistral Medium, etc.)
* Google Vertex AI (Gemini 1.5 Pro, etc.)
* Cohere (Command, Command-R, etc.)
* AWS Bedrock (Claude, Titan, etc.)
* Local/Private Models

<Card title="Supported Providers" icon="server" href="/docs/aigw/integrations/llms">
  See the full list of LLM providers supported by the AI Gateway
</Card>

### 4. Guardrails for Safe Agents

Guardrails ensure your Strands agents operate safely and respond appropriately in all situations.

**Why Use Guardrails?**

Strands agents can experience various failure modes:

* Generating harmful or inappropriate content
* Leaking sensitive information like PII
* Hallucinating incorrect information
* Generating outputs in incorrect formats

The AI Gateway's guardrails can:

* Detect and redact PII in both inputs and outputs
* Filter harmful or inappropriate content
* Validate response formats against schemas
* Check for hallucinations against ground truth
* Apply custom business logic and rules

<Card title="Learn More About Guardrails" icon="shield-check" href="/docs/aigw/product/guardrails">
  Explore the AI Gateway's guardrail features to enhance agent safety
</Card>

## Advanced Configuration

<Tabs>
  <Tab title="Environment-Specific Settings">
    Configure different behavior for development, staging, and production:
  </Tab>

  <Tab title="Request-Level Overrides">
    Override configuration for specific requests without changing the model:
  </Tab>
</Tabs>

***

## Enterprise Governance

If you are using Strands inside your organisation, you need to consider several governance aspects:

* **Cost Management**: Controlling and tracking AI spending across teams
* **Access Control**: Managing which teams can use specific models
* **Usage Analytics**: Understanding how AI is being used across the organisation
* **Security & Compliance**: Maintaining enterprise security standards
* **Reliability**: Ensuring consistent service across all users

### Centralized Key Management

Instead of distributing raw API keys to developers, use AI Gateway API keys that you can control centrally:

```python theme={"system"}
# Developers use AI Gateway API keys (not raw provider keys)
model = OpenAIModel(
    client_args={
        "api_key": "pk-team-frontend-xyz123",  # Team-specific AI Gateway API key
        "base_url": "https://aigw.portkey.ai/v1"
    },
    model_id="gpt-4o",
    params={"temperature": 0.7}
)
```

You can:

* **Rotate provider keys** without updating any code
* **Set spending limits** per team or API key
* **Control model access** (which teams can use which models)
* **Monitor usage** across all teams and projects
* **Revoke access** instantly if needed

### Usage Analytics & Budgets

Track and control AI spending across your organisation:

* **Per-team budgets**: Set monthly spending limits for different teams
* **Model usage analytics**: See which teams are using which models most
* **Cost attribution**: Understand costs by project, team, or user
* **Usage alerts**: Get notified when teams approach their limits

All of this works automatically with your existing Strands agents—no code changes required.

***

## Contact & Support

<CardGroup cols={2}>
  <Card title="Enterprise SLAs & Support" icon="headset" href="https://stratacloudmanager.paloaltonetworks.com/">
    Get dedicated SLA-backed support.
  </Card>

  <Card title="AI Gateway Community" icon="users" href="https://community.portkey.ai">
    Join our forums and Slack channel.
  </Card>
</CardGroup>

***

## Resources

<CardGroup cols={3}>
  <Card title="Strands Agents Docs" icon="book" href="https://strandsagents.com/" />
</CardGroup>

### Troubleshooting

<AccordionGroup>
  <Accordion title="Import Errors">
    **Problem**: `ModuleNotFoundError` when importing the AI Gateway components

    **Solution**: Ensure all dependencies are installed:

    ```bash theme={"system"}
    pip install -U strands-agents strands-agents-tools openai
    ```

    Verify versions are compatible:
  </Accordion>

  <Accordion title="Authentication Errors">
    **Problem**: `AuthenticationError` when making requests

    **Solution**: Verify your AI Gateway API key and provider setup: Verify your AI Gateway API key and provider setup. Test your AI Gateway API key directly and check for common issues such as wrong API key format, misconfigured provider, and missing config attachments.
  </Accordion>

  <Accordion title="Rate Limiting">
    **Problem**: Hitting rate limits despite having fallbacks configured

    **Solution**: Check your fallback configuration:

    ```python theme={"system"}
    import json
    # Ensure fallbacks are configured for rate limit status codes
    headers = {
        "x-portkey-config": json.dumps({
            "strategy": {
                "mode": "fallback",
                "on_status_codes": [429, 503, 502, 504]
            },
            "targets": [
                {"provider":"@primary-key"},
                {"provider":"@backup-key"}
            ]
        }),
    }
    ```

    Also verify that your backup providers have sufficient quota.
  </Accordion>

  <Accordion title="Model Compatibility">
    **Problem**: Model not found or unsupported model errors

    **Solution**: Check that your model ID is correct for the provider:

    ```python theme={"system"}
    # OpenAI models
    model_id="gpt-4o",  # Correct
    model_id = "gpt-4-turbo"  # Correct

    # Anthropic models
    model_id="claude-3-5-sonnet-20241022",  # Correct
    model_id = "claude-3-sonnet"  # Wrong format

    # Use provider-specific model IDs, not generic names
    ```
  </Accordion>

  <Accordion title="Missing Traces/Logs">
    **Problem**: Not seeing traces or logs in Strata Cloud Manager

    **Solution**: Verify your requests are going through the AI Gateway:

    ```python theme={"system"}
    import json
    # Check that base_url is set correctly
    print(model.client.base_url)  # Should be https://aigw.portkey.ai/v1

    # Add trace IDs for easier debugging
    headers = {
        "x-portkey-trace-id": "debug-session-123",
        "x-portkey-metadata": json.dumps({"debug": "true"}),
    }
    ```

    Also check the Logs section in Strata Cloud Manager and filter by your metadata.
  </Accordion>
</AccordionGroup>

### Frequently Asked Questions

<AccordionGroup>
  <Accordion title="How does the AI Gateway enhance Strands Agents?">
    The AI Gateway adds production-readiness to Strands Agents through comprehensive observability (traces, logs, metrics), reliability features (fallbacks, retries, caching), and access to 3,000+ LLMs through a unified interface. This makes it easier to debug, optimize, and scale your agent applications, all while preserving Strands Agents' strong type safety.
  </Accordion>

  <Accordion title="Can I use the AI Gateway with existing Strands Agents applications?">
    Yes! The AI Gateway integrates seamlessly with existing Strands Agents applications. You just need to replace your client initialization code with the gateway-enabled version. The rest of your agent code remains unchanged and continues to benefit from Strands Agents' strong typing.
  </Accordion>

  <Accordion title="Does the AI Gateway work with all Strands Agents features?">
    The AI Gateway supports all Strands Agents features, including tool use, multi-agent systems, and more. It adds observability and reliability without limiting any of the framework's functionality.
  </Accordion>

  <Accordion title="Can I track usage across multiple agents in a workflow?">
    Yes, the AI Gateway allows you to use a consistent `trace_id` across multiple agents and requests to track the entire workflow. This is especially useful for multi-agent systems where you want to understand the full execution path.
  </Accordion>

  <Accordion title="How do I filter logs and traces for specific agent runs?">
    The AI Gateway allows you to add custom metadata to your agent runs, which you can then use for filtering. Add fields like `agent_name`, `agent_type`, or `session_id` to easily find and analyze specific agent executions.
  </Accordion>

  <Accordion title="Can I use my own API keys with the AI Gateway?">
    Yes! The AI Gateway uses your own API keys for the various LLM providers. It securely stores them, allowing you to easily manage and rotate keys without changing your code.
  </Accordion>
</AccordionGroup>

***

## Next Steps

Now that you have the AI Gateway integrated with your Strands agents:

1. **Monitor your agents** in the [Strata Cloud Manager](https://stratacloudmanager.paloaltonetworks.com/) to understand their behavior
2. **Set up fallbacks** for critical production agents using multiple providers
3. **Add custom metadata** to track different agent types or user segments
4. **Configure budgets and alerts** if you're deploying multiple agents
5. **Explore advanced routing** to optimize for cost, latency, or quality

<CardGroup cols={3}>
  <Card title="Strata Cloud Manager" icon="chart-line" href="https://stratacloudmanager.paloaltonetworks.com/">
    View your agent logs, traces, and analytics
  </Card>

  <Card title="Supported Models" icon="server" href="/docs/aigw/integrations/llms">
    See all 3,000+ models you can use with this integration
  </Card>

  <Card title="Governance & Administration" icon="building" href="/docs/aigw/introduction/feature-overview#governance-%26-administration">
    Explore access control, encryption, and audit trail features
  </Card>
</CardGroup>


## Related topics

- [AWS AgentCore](/docs/aigw/integrations/agents/agentcore.md)
- [Overview](/docs/aigw/integrations/agents.md)
- [Agentic Usage](/docs/aigw/api-reference/inference-api/agentic-usage.md)
- [Agent Gateway](/docs/aigw/product/agent-gateway.md)
- [Agent Servers](/docs/aigw/product/agent-gateway/servers.md)