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

# Agent Profiles

> Manage browser automation profiles, authentication credentials, 2FA, and cookies persistence for consistent execution environments

Agent profiles in Asteroid provide a way to create consistent, reusable browser automation environments. Each profile contains configuration settings for proxies and captcha solving, along with associated credentials for authentication across different websites and services.

<CardGroup cols={1}>
  <Card title="Agent Profiles" icon="browser" href="#agent-profiles" horizontal>
    Configure browser settings, proxy configurations, and automation parameters
  </Card>

  <Card title="Credentials Management" icon="key" href="#credentials-management" horizontal>
    Securely store and manage authentication data for your automation workflows
  </Card>

  <Card title="Profile Pools" icon="layer-group" href="#profile-pools" horizontal>
    Group multiple profiles for automatic selection and credential rotation
  </Card>
</CardGroup>

## Quick Start

<Steps>
  <Step title="Create an Agent Profile">
    Use the Asteroid dashboard to create a new agent profile with your desired proxy settings, captcha solver configuration, and automation features.
    You can also create profiles via the API and SDKs:

    * [Create an agent profile](/api-reference/agent-profiles/create-agent-profile)
    * [TypeScript SDK](/sdks/typescript)
    * [Python SDK](/sdks/python)
  </Step>

  <Step title="Add Credentials (Optional)">
    If your automation requires authentication, add credentials to your profile through the dashboard's credential management interface.
  </Step>

  <Step title="Execute with Profile">
    Execute your agent using the profile through either the dashboard or SDK:

    <Tabs>
      <Tab title="Dashboard">
        1. Navigate to the **Agents** section in your Asteroid dashboard
        2. Select the agent you want to execute
        3. Choose your created profile from the dropdown next to Run Agent
        4. Provide your input data and click Run
        5. Monitor the execution progress in real-time
      </Tab>

      <Tab title="SDK">
        Use the SDK to programmatically execute your agent with the specific profile:

        <CodeGroup>
          ```ts TypeScript theme={null}
          import { client, agentExecutePost } from 'asteroid-odyssey';

          client.setConfig({
            headers: { 'X-Asteroid-Agents-Api-Key': 'your-api-key' },
          });

          const { data } = await agentExecutePost({
            path: { agentId: 'YOUR_AGENT_ID' },
            body: {
              inputs: { input: 'your data' },
              agentProfileId: 'YOUR_AGENT_PROFILE_ID',
            },
          });
          ```

          ```python Python theme={null}
          import os
          from asteroid_odyssey import Configuration, ApiClient
          from asteroid_odyssey.api.agents_api import AgentsApi
          from asteroid_odyssey.models.agents_agent_execute_agent_request import AgentsAgentExecuteAgentRequest

          config = Configuration(api_key={"ApiKeyAuth": "your-api-key"})
          with ApiClient(config) as api_client:
              agents_api = AgentsApi(api_client)
              response = agents_api.agent_execute_post(
                  agent_id="your-agent-id",
                  agents_agent_execute_agent_request=AgentsAgentExecuteAgentRequest(
                      inputs={"input": "your data"},
                      agent_profile_id="your-profile-id",
                  ),
              )
          ```
        </CodeGroup>
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Agent Profiles

Agent profiles define the browser automation environment settings that will be used during execution. These profiles ensure consistent behavior across different automation runs and provide isolation between different use cases.

### Profile Configuration

Each agent profile contains the following key components:

<AccordionGroup>
  <Accordion title="Proxy Settings">
    * **Proxy Country Code**: Two-letter lowercase country code for proxy location (e.g., "us", "uk", "de")
    * **Proxy Type**: Type of proxy connection to use
    * **Persistent IP**: Whether to maintain the same IP address across requests
      <Warning> Persistent IP's can only be used with a US proxy and do not support Mobile proxies or Captcha Solving </Warning>
  </Accordion>

  <Accordion title="Automation Features">
    * **Captcha Solver**: Enable/disable automatic captcha solving capabilities
    * **Cookies**: Profiles can preload and persist site cookies. You can create profiles with cookies, and add/remove cookies later via the SDK. Useful for keeping authenticated sessions or site preferences.
    * **Cache Persistence**: Control whether browser cache and cookies are retained between executions. When enabled (default), the profile maintains session state, cookies, and cached data across runs for seamless continuity. When disabled, each execution starts with a fresh browser state. Cache can be manually cleared at any time using the "Clear Cache" option.
  </Accordion>
</AccordionGroup>

<Info>
  Agent profiles can be created and managed through the dashboard, the API, and SDKs.
  See [Create an agent profile](/api-reference/agent-profiles/create-agent-profile), [List agent profiles](/api-reference/agent-profiles/list-agent-profiles), [TypeScript SDK](/sdks/typescript), and [Python SDK](/sdks/python).
</Info>

<Warning>
  Deleting a profile will affect any executions that reference it. Ensure no active automations depend on the profile before deletion.
</Warning>

## Credentials Management

Store credentials securely by linking them to an **agent profile**.

In the **Vault** section, enter the credential name and value. The platform mirrors vault names into **placeholder tokens** of the form `##CREDENTIAL_NAME##` (uppercase with underscores matching how the name is normalized for substitution).

Your automations can use these placeholders in:

* **AI Task instructions** (for tools that consume templated prompts—still avoid pasting raw secrets into chat logs).
* **Playwright scripts** — the runtime injects decrypted values only into browser automation inputs, not into arbitrary shell or file tools, to reduce accidental leakage.

This injection path is separate from **`__PLACEHOLDER__` templates** in **scripted mode** scripts on AI Task nodes. Those systems resolve values from LLM reasoning or structured variable definitions, not from the vault’s `##...##` map. See [AI Task node](/fundamentals/nodes/ai-task).

For more information, see [Security](/support-security/security).

<Warning>Never paste real secrets into instructions or scripts as plain text—use vault placeholders or dedicated variable mechanisms instead.</Warning>

## Profile Pools

Profile pools allow you to group multiple agent profiles together so the system automatically selects one at execution time. Instead of manually choosing a single profile for each execution, you point to a pool and Asteroid picks the best available profile for you.

<Info>
  Profile pools can be created and managed through the dashboard, the API, and SDKs.
  See [Create a pool](/api-reference/agent-profile-pools/create-agent-profile-pool), [List pools](/api-reference/agent-profile-pools/list-agent-profile-pools), [Update a pool](/api-reference/agent-profile-pools/update-agent-profile-pool), and [Add pool members](/api-reference/agent-profile-pools/add-profiles-to-pool).
</Info>

### Why Use Profile Pools?

Profile pools solve common challenges in browser automation:

* **Avoid credential conflicts**: Prevent simultaneous use of the same account across multiple executions
* **Distribute load**: Spread requests across multiple accounts to respect rate limits
* **Improve reliability**: Automatically use alternative profiles when one is unavailable
* **Reduce friction**: Eliminate manual profile selection for each execution

<Info>
  Think of profile pools as a "rotation strategy" for your automation credentials. Rather than hard-coding a specific profile, you define a pool of profiles and let the system intelligently choose which one to use.
</Info>

### Selection Strategies

Profile pools support two selection strategies that determine which profile gets picked for each execution:

<AccordionGroup>
  <Accordion title="Least Recently Used (Default)">
    Selects the profile that hasn't been used for the longest time. This distributes load evenly across all profiles in the pool.

    **Best for:**

    * Spreading requests across accounts to avoid rate limits
    * Rotating through multiple accounts fairly
    * Scenarios where you want to minimize repeated use of the same profile

    **Example**: If you have profiles A, B, and C, and the last execution used profile B, the next execution will prefer profile A (if it was used longest ago), then C, then B.
  </Accordion>

  <Accordion title="Most Recently Used">
    Selects the most recently used profile. This concentrates activity on fewer "warm" profiles.

    **Best for:**

    * Keeping sessions warm and browser state cached
    * Reusing authenticated sessions when possible
    * Scenarios where session continuity matters more than distribution

    **Example**: If profile B was just used successfully, the next execution will try to use profile B again to maintain session state.
  </Accordion>
</AccordionGroup>

### Concurrent Use Control

Control whether a profile can be selected while it's already being used by another running execution:

* **`allowConcurrentUse: false` (default)** — A profile that is currently tied to an active execution will be skipped. If all profiles in the pool are busy, the execution request fails immediately.
  * **Best for:** Strict credential isolation where you never want the same account used simultaneously
  * **Use when:** The target site enforces per-session limits or you need guaranteed isolation

* **`allowConcurrentUse: true`** — Any profile can be selected regardless of whether it's currently in use by another execution.
  * **Best for:** High-throughput scenarios where the target site doesn't enforce strict per-session limits
  * **Use when:** You want maximum availability and don't need credential isolation

<Warning>
  If `allowConcurrentUse` is set to `false` and all profiles in the pool are currently in use, new execution requests will fail with an error indicating no profiles are available. Consider adding more profiles to your pool or enabling concurrent use.
</Warning>

### Quick Start

<Steps>
  <Step title="Create a Pool">
    Create a new profile pool via the platform or programmatically:

    <Tabs>
      <Tab title="Platform">
        1. Navigate to **Agent Profiles** in your Asteroid dashboard
        2. Click **Create Profile Pool**
        3. Provide a unique name for your pool
        4. Choose your selection strategy (Least Recently Used or Most Recently Used)
        5. Configure concurrent use setting
        6. Click **Create**
      </Tab>

      <Tab title="SDK">
        Use the platform today, or call the profile pool endpoints directly:

        * [Create an agent profile pool](/api-reference/agent-profile-pools/create-agent-profile-pool)
        * [List agent profile pools](/api-reference/agent-profile-pools/list-agent-profile-pools)
        * [Get an agent profile pool](/api-reference/agent-profile-pools/get-agent-profile-pool)
      </Tab>
    </Tabs>
  </Step>

  <Step title="Add Profiles to the Pool">
    Select existing agent profiles to include in your pool:

    <Tabs>
      <Tab title="Platform">
        1. Open your newly created profile pool
        2. Click **Add Profiles**
        3. Select the agent profiles you want to include
        4. Click **Add to Pool**
      </Tab>

      <Tab title="SDK">
        Add pool members through the profile pool API pages:

        * [Add pool members](/api-reference/agent-profile-pools/add-profiles-to-pool)
        * [List pool members](/api-reference/agent-profile-pools/list-pool-members)
        * [Remove pool members](/api-reference/agent-profile-pools/remove-profiles-from-pool)
      </Tab>
    </Tabs>
  </Step>

  <Step title="Execute with the Pool">
    Use the pool ID when triggering an execution instead of specifying a profile ID:

    <Tabs>
      <Tab title="Platform">
        1. Navigate to your agent
        2. Click **Run Agent**
        3. Select your profile pool from the dropdown (instead of a single profile)
        4. Provide your input data and click **Run**
        5. The system will automatically select an available profile from the pool
      </Tab>

      <Tab title="SDK">
        Profile pools are available through the platform and the API endpoint pages.

        Use [Execute an agent](/api-reference/agents/execute-an-agent) and pass `agentProfilePoolId` in the request body when you want the API to choose a profile from a pool.
      </Tab>
    </Tabs>
  </Step>
</Steps>

### Important Constraints

<AccordionGroup>
  <Accordion title="Mutual Exclusivity">
    The API treats `agentProfileId` and `agentProfilePoolId` as mutually exclusive. You must specify one or the other, but not both.

    **Correct:**

    ```json theme={null}
    { "agentProfileId": "profile-123" }

    { "agentProfilePoolId": "pool-456" }
    ```

    **Incorrect:**

    ```json theme={null}
    {
      "agentProfileId": "profile-123",
      "agentProfilePoolId": "pool-456"
    }
    ```
  </Accordion>

  <Accordion title="Organization Scope">
    * All profiles in a pool must belong to the same organization
    * Pool names must be unique within an organization
    * Profiles cannot be added to pools from different organizations
  </Accordion>

  <Accordion title="Availability Requirements">
    * A pool must contain at least one profile to be used for executions
    * If `allowConcurrentUse` is `false` and all profiles are in use, execution requests will fail
    * Removing the last profile from a pool will prevent new executions from using that pool
  </Accordion>

  <Accordion title="Recommended Pool Size">
    The number of profiles in your pool should match your expected parallelism. For example, if you need to run 5 agent executions simultaneously, you need at least 5 profiles in the pool. We recommend having 1-2 extra profiles as buffer for peak loads.
  </Accordion>
</AccordionGroup>

<Info>
  Profile pools work seamlessly with all profile features including credentials, cookies, TOTP secrets, and cache persistence. The selected profile's configuration applies to the execution as if you had manually chosen that specific profile.
</Info>

## 2FA - TOTP Secrets

Set up Two-Factor Authentication (2FA) using Time-based One-Time Passwords (TOTP) with our TOTP tool. Asteroid supports all standard TOTP providers including Google Authenticator, Microsoft Authenticator, Authy, 1Password, and others.

<Info>
  TOTP provides an additional layer of security by generating time-based codes that expire after 30 seconds. This prevents unauthorized access even if your password is compromised. Our TOTP tool works with any service that provides a standard TOTP secret key.
</Info>

<Steps>
  <Step title="Obtain TOTP Secret Key">
    Get your TOTP secret key from your service provider. The process varies by provider:

    **Google Account:**

    1. Navigate to your [Google Account](https://myaccount.google.com/) → **Security**
    2. Go to **2-Step Verification** → **Authenticator app** → **Set up authenticator**
    3. Click **Can't scan it?** to reveal the 32-character setup key

    **Other Popular Services:**

    * **Microsoft Authenticator**: Microsoft Account → Security → Advanced security options → Add sign-in method
    * **GitHub**: Settings → Password and authentication → Two-factor authentication → Set up using an app
    * **AWS**: IAM Console → Users → Security credentials → Assign MFA device
    * **Discord**: User Settings → My Account → Enable Two-Factor Auth
    * **Most Services**: Look for "manual entry", "can't scan", or "setup key" options that reveal the secret key
    * The key is typically a 16-32 character alphanumeric string (Base32 encoded)
  </Step>

  <Step title="Create TOTP Secret in Vault">
    In your Agent Profile's **Vault**, create a new TOTP Secret credential and paste the secret key as the credential value. You can name your credential anything as long as it has the prefix `TOTP_`.
  </Step>

  <Step title="Add TOTP Tool to Agent">
    Add the **Generate TOTP Secret** tool to the agent node where you want to use TOTP.
  </Step>

  <Step title="Test Configuration">
    Execute your agent with the configured profile.
  </Step>
</Steps>

## Inbox Email

Every agent profile is automatically provisioned with its own email inbox at `{prefix}@agentmail.asteroid.ai`. The default prefix is the profile's UUID, and you can override it by setting an **Inbox Email Prefix** on the profile (for example, `acme-support` resolves to `acme-support@agentmail.asteroid.ai`).

Agents can read and send from this inbox by enabling the `send_mail` and `get_mail` tools on AI Task nodes (under the **Communication** capability). A common use case is **receiving email login / verification codes** — instruct the agent to poll its inbox until the code arrives, then extract it and continue the flow.

See [Agent Emails](/fundamentals/emails) for the full guide, including a prompt template for catching verification codes.

## Cookies on Agent Profiles

Profiles can store website cookies to persist authenticated sessions and preferences across runs. Add cookies when creating a profile, or manage them later via the API.

```ts theme={null}
type Cookie = {
  id?: string;       // present on existing cookies
  name: string;      // display name
  key: string;       // cookie name
  value: string;     // cookie value
  domain: string;    // e.g. '.example.com'
  secure: boolean;
  http_only: boolean;
  same_site: 'Strict' | 'Lax' | 'None';
  expiry?: string;   // ISO 8601
  created_at: string; // ISO 8601
}
```

### SDK Methods

See the SDK for creation and management details: [TypeScript SDK](/sdks/typescript) and [Python SDK](/sdks/python). The Asteroid SDK provides a simple interface for using agent profiles during execution:

<CodeGroup>
  ```ts TypeScript theme={null}
  import { client, agentExecutePost } from 'asteroid-odyssey';

  client.setConfig({
    headers: { 'X-Asteroid-Agents-Api-Key': 'YOUR_API_KEY' },
  });

  // Execute an agent with a specific profile
  const { data } = await agentExecutePost({
    path: { agentId: 'YOUR_AGENT_ID' },
    body: {
      inputs: { key: 'value' },
      agentProfileId: 'YOUR_AGENT_PROFILE_ID',
    },
  });
  ```

  ```python Python theme={null}
  import os
  from asteroid_odyssey import Configuration, ApiClient
  from asteroid_odyssey.api.agents_api import AgentsApi
  from asteroid_odyssey.models.agents_agent_execute_agent_request import AgentsAgentExecuteAgentRequest

  config = Configuration(api_key={"ApiKeyAuth": "YOUR_API_KEY"})
  with ApiClient(config) as api_client:
      agents_api = AgentsApi(api_client)
      # Execute an agent with a specific profile
      response = agents_api.agent_execute_post(
          agent_id="YOUR_AGENT_ID",
          agents_agent_execute_agent_request=AgentsAgentExecuteAgentRequest(
              inputs={"key": "value"},
              agent_profile_id="YOUR_AGENT_PROFILE_ID",
          ),
      )
  ```
</CodeGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Profile Not Found">
    **Error**: Agent profile not found

    **Causes**:

    * Profile was deleted
    * Incorrect profile ID or name
    * Profile belongs to different organization

    **Solutions**:

    * Verify the profile ID/name is correct
    * Check organization access permissions
    * Use the list profiles API to confirm available profiles
  </Accordion>
</AccordionGroup>

***

<Note>
  For additional help with agent profiles and credentials, consult the [SDK documentation](/sdks/setup) or contact our [support](/support-security/support).
</Note>