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

# Creating Your First Agent

> Step-by-step guide to setting up your first Bloom agent

## Prerequisites

Before creating your first agent, ensure you have:

* Admin access to your Bloom organization
* API credentials for the services you want to integrate
* Basic understanding of HTTP APIs

## Step 1: Create an Integration

<Steps>
  <Step title="Navigate to Integrations">
    Go to the **Integrations** tab in your Bloom dashboard
  </Step>

  <Step title="Add Service">
    Click **"Add Integration"** and select your desired service (e.g., OpenAI, GitHub, Serper)
  </Step>

  <Step title="Configure Credentials">
    Enter your API key and any required configuration for the service

    <Warning>
      Store your API keys securely. Bloom encrypts them but ensure they have appropriate permissions.
    </Warning>
  </Step>

  <Step title="Test Connection">
    Use the test button to verify your integration is working correctly
  </Step>
</Steps>

## Step 2: Define Scopes

Scopes control what your agent can access. Create granular permissions:

<Steps>
  <Step title="Go to Scopes Tab">
    Navigate to the **Scopes** section in your dashboard
  </Step>

  <Step title="Create New Scope">
    Click **"Create Scope"** and give it a descriptive name
  </Step>

  <Step title="Configure Permissions">
    Set up the allowed HTTP methods and API paths:

    ```json theme={null}
    {
      "service": "openai",
      "methods": ["POST"],
      "paths": ["/chat/completions", "/embeddings"]
    }
    ```
  </Step>

  <Step title="Save Scope">
    Review and save your scope configuration
  </Step>
</Steps>

## Step 3: Create Your Agent

<Steps>
  <Step title="Navigate to Agents">
    Go to the **Agents** tab in your dashboard
  </Step>

  <Step title="Add New Agent">
    Click **"Create Agent"** and provide:

    * **Name**: Descriptive name for your agent
    * **Description**: What this agent does
  </Step>

  <Step title="Assign Scopes">
    Select the scopes you created in Step 2

    <Tip>
      You can assign multiple scopes to give your agent access to different services
    </Tip>
  </Step>

  <Step title="Generate Agent ID">
    Copy your agent ID - you'll need this for implementation
  </Step>
</Steps>

## Step 4: Implement in Code

Choose your integration method:

<Tabs>
  <Tab title="Direct API">
    ```python theme={null}
    import requests
    import os

    AGENT_ID = os.getenv("BLOOM_AGENT_ID")
    ORG_API_KEY = os.getenv("BLOOM_ORG_API_KEY")

    def call_openai(prompt):
        response = requests.post(
            "https://iam.bloomtechnologies.app/https://api.openai.com/v1/chat/completions",
            headers={"Authorization": f"Bearer {ORG_API_KEY}"},
            json={
                "agent_id": AGENT_ID,
                "model": "gpt-3.5-turbo",
                "messages": [{"role": "user", "content": prompt}],
                "max_tokens": 150
            }
        )
        return response.json()

    # Test your agent
    result = call_openai("Hello from my Bloom agent!")
    print(result)
    ```
  </Tab>

  <Tab title="MCP Server">
    Add to your `mcp_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "openai": {
          "command": "npx",
          "args": ["-y", "bloom-mcp-wrapper", "@modelcontextprotocol/server-openai"],
          "env": {
            "BLOOM_AUTH": "bloom_{ORG_KEY}_agent_{AGENT_ID}"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Verification

Test that everything is working:

1. **Check Agent Status**: Verify your agent appears in the dashboard
2. **Test API Call**: Make a simple request through the proxy
3. **Review Logs**: Check the activity logs in your dashboard
4. **Validate Scopes**: Ensure your agent can only access permitted endpoints

<Note>
  If you encounter authentication errors, double-check your environment variables and scope assignments.
</Note>

## Common Issues

<AccordionGroup>
  <Accordion title="403 Forbidden Error">
    Your agent likely doesn't have the required scopes. Check:

    * Agent has the correct scopes assigned
    * Scope includes the HTTP method you're using
    * Scope includes the exact API path
  </Accordion>

  <Accordion title="Invalid Agent ID">
    Verify:

    * BLOOM\_AGENT\_ID environment variable is set correctly
    * Agent ID exists in your dashboard
    * Agent hasn't been deleted or deactivated
  </Accordion>

  <Accordion title="Integration Not Found">
    Ensure:

    * Integration exists and is properly configured
    * Service name in URL matches integration name
    * API credentials are valid and have necessary permissions
  </Accordion>
</AccordionGroup>

## Next Steps

* [Set up environment variables](/guides/environment-setup)
* [Learn about proxy routing](/api-reference/proxy-routing)
* [Explore advanced integration patterns](/integrations/overview)