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

# Python-SDK

> Typsichere Python-Bibliothek für die itellicoAI API

export const Screenshot = ({lightSrc, darkSrc, alt, caption, maxWidth = "880px"}) => {
  return <div style={{
    margin: "1rem auto",
    maxWidth,
    width: "100%"
  }}>
      <Frame>
        <img className="block dark:hidden" src={lightSrc} alt={alt} />
        <img className="hidden dark:block" src={darkSrc} alt={alt} />
      </Frame>
      {caption ? <p style={{
    marginTop: "0.5rem",
    fontSize: "0.875rem",
    color: "inherit",
    opacity: 0.8
  }}>
          {caption}
        </p> : null}
    </div>;
};

## Installation

<CodeGroup>
  ```bash pip theme={null}
  pip install itellicoai
  ```

  ```bash poetry theme={null}
  poetry add itellicoai
  ```
</CodeGroup>

## Voraussetzungen

* Python 3.9+
* Unterstützt sowohl synchrone als auch asynchrone Operationen

***

## Hol dir deinen API-Schlüssel

Um das SDK zu nutzen, brauchst du einen API-Schlüssel aus deinem [itellicoAI-Dashboard](https://app.itellico.ai):

<Steps>
  <Step title="Zu API-Schlüsseln gehen">
    Gehe zu **Entwickler → API-Schlüssel**
  </Step>

  <Step title="Schlüssel erstellen">
    Klicke auf **API-Schlüssel erstellen**
  </Step>

  <Step title="Schlüssel kopieren">
    Kopiere den generierten Schlüssel - er wird nur einmal angezeigt
  </Step>
</Steps>

<Screenshot lightSrc="/images/accounts__api-keys_DE-light.png" darkSrc="/images/accounts__api-keys_DE-dark.png" alt="Seite zur Verwaltung von API-Schlüsseln" />

<Warning>
  Speichere deinen API-Schlüssel sicher mit Umgebungsvariablen. Checke ihn niemals in die Versionsverwaltung ein.
</Warning>

***

## Schnellstart

```python theme={null}
from itellicoai import Itellicoai

# Initialize client
client = Itellicoai(
    api_key="your-api-key"
)

# Create an agent
agent = client.agents.create(
    account_id="your-account-id",
    name="Customer Support Agent",
    model={
        "provider": "openai",
        "model": "gpt-4o-mini"
    },
    voice={
        "provider": "elevenlabs",
        "voice_id": "EXAVITQu4vr4xnSDxMaL"
    },
    transcriber={
        "provider": "deepgram",
        "model": "nova-2:general",
        "language": "en-US"
    },
    initial_message={
        "mode": "fixed_message",
        "message": "Hello! How can I assist you today?",
        "delay_ms": 1000
    },
    max_duration_seconds=1800,
    tags=["support", "customer-service"]
)

print(f"Created agent: {agent.id}")
```

***

## Asynchrone Unterstützung

```python theme={null}
import asyncio
from itellicoai import AsyncItellicoai

async def main():
    client = AsyncItellicoai(api_key="your-api-key")

    # List agents asynchronously
    agents = await client.agents.list("account_id")

    for agent in agents.items:
        print(f"Agent: {agent.name}")

asyncio.run(main())
```

***

## SDK-Operationen

<AccordionGroup>
  <Accordion title="Agentenverwaltung" defaultOpen>
    ### Agenten auflisten

    ```python theme={null}
    from itellicoai import Itellicoai

    client = Itellicoai(
        api_key="My API Key",
    )
    agents = client.agents.list(
        account_id="account_id",
    )
    print(agents.count)
    ```

    ### Agent abrufen

    ```python theme={null}
    from itellicoai import Itellicoai

    client = Itellicoai(
        api_key="My API Key",
    )
    agent_response = client.agents.retrieve(
        agent_id="agent_id",
        account_id="account_id",
    )
    print(agent_response.id)
    ```

    ### Agent aktualisieren

    ```python theme={null}
    from itellicoai import Itellicoai

    client = Itellicoai(
        api_key="My API Key",
    )
    agent_response = client.agents.update(
        agent_id="agent_id",
        account_id="account_id",
    )
    print(agent_response.id)
    ```

    ### Agent archivieren

    ```python theme={null}
    from itellicoai import Itellicoai

    client = Itellicoai(
        api_key="My API Key",
    )
    client.agents.archive(
        agent_id="agent_id",
        account_id="account_id",
    )
    ```
  </Accordion>

  <Accordion title="Gespräche">
    ### Gespräche auflisten

    ```python theme={null}
    from itellicoai import Itellicoai

    client = Itellicoai(api_key="My API Key")

    conversations = client.accounts.list_conversations(
        account_id="account_id"
    )

    for conv in conversations.items:
        print(f"Conversation ID: {conv.conversation_id}")
        print(f"Contact: {conv.contact_number}")
        print(f"Duration: {conv.duration_seconds}s")
        print(f"Status: {conv.status}")
    ```
  </Accordion>

  <Accordion title="Telefonnummern">
    ### Telefonnummern auflisten

    ```python theme={null}
    from itellicoai import Itellicoai

    client = Itellicoai(
        api_key="My API Key",
    )
    phone_numbers = client.accounts.phone_numbers.list(
        account_id="account_id",
    )
    print(phone_numbers.count)
    ```

    ### Telefonnummer erstellen

    ```python theme={null}
    from itellicoai import Itellicoai

    client = Itellicoai(
        api_key="My API Key",
    )
    phone_number = client.accounts.phone_numbers.create(
        account_id="account_id",
        sip_trunk_id="sip_trunk_id",
    )
    print(phone_number.id)
    ```

    ### Telefonnummer abrufen

    ```python theme={null}
    from itellicoai import Itellicoai

    client = Itellicoai(
        api_key="My API Key",
    )
    phone_number = client.accounts.phone_numbers.retrieve(
        phone_number_id="phone_number_id",
        account_id="account_id",
    )
    print(phone_number.id)
    ```

    ### Telefonnummer aktualisieren

    ```python theme={null}
    from itellicoai import Itellicoai

    client = Itellicoai(
        api_key="My API Key",
    )
    phone_number = client.accounts.phone_numbers.update(
        phone_number_id="phone_number_id",
        account_id="account_id",
    )
    print(phone_number.id)
    ```

    ### Telefonnummer löschen

    ```python theme={null}
    from itellicoai import Itellicoai

    client = Itellicoai(
        api_key="My API Key",
    )
    client.accounts.phone_numbers.delete(
        phone_number_id="phone_number_id",
        account_id="account_id",
    )
    ```
  </Accordion>

  <Accordion title="Anbieter">
    ### Modelle auflisten

    ```python theme={null}
    from itellicoai import Itellicoai

    client = Itellicoai(
        api_key="My API Key",
    )

    response = client.accounts.providers.list_models(
        account_id="account_id",
    )
    print(response)
    ```

    ### Transkribierer auflisten

    ```python theme={null}
    from itellicoai import Itellicoai

    client = Itellicoai(
        api_key="My API Key",
    )

    response = client.accounts.providers.list_transcribers(
        account_id="account_id",
    )
    print(response)
    ```

    ### Stimmen auflisten

    ```python theme={null}
    from itellicoai import Itellicoai

    client = Itellicoai(
        api_key="My API Key",
    )

    response = client.accounts.providers.list_voices(
        account_id="account_id",
        provider="provider",
    )
    print(response)
    ```
  </Accordion>

  <Accordion title="SIP-Trunks">
    ### SIP-Trunks auflisten

    ```python theme={null}
    from itellicoai import Itellicoai

    client = Itellicoai(
        api_key="My API Key",
    )

    sip_trunks = client.accounts.sip_trunks.list(
        account_id="account_id",
    )
    print(sip_trunks.count)
    ```

    ### SIP-Trunk erstellen

    ```python theme={null}
    from itellicoai import Itellicoai

    client = Itellicoai(
        api_key="My API Key",
    )

    sip_trunk = client.accounts.sip_trunks.create(
        account_id="account_id",
    )
    print(sip_trunk.id)
    ```

    ### SIP-Trunk abrufen

    ```python theme={null}
    from itellicoai import Itellicoai

    client = Itellicoai(
        api_key="My API Key",
    )

    sip_trunk = client.accounts.sip_trunks.retrieve(
        sip_trunk_id="sip_trunk_id",
        account_id="account_id",
    )
    print(sip_trunk.id)
    ```

    ### SIP-Trunk aktualisieren

    ```python theme={null}
    from itellicoai import Itellicoai

    client = Itellicoai(
        api_key="My API Key",
    )

    sip_trunk = client.accounts.sip_trunks.update(
        sip_trunk_id="sip_trunk_id",
        account_id="account_id",
    )
    print(sip_trunk.id)
    ```

    ### SIP-Trunk löschen

    ```python theme={null}
    from itellicoai import Itellicoai

    client = Itellicoai(
        api_key="My API Key",
    )

    client.accounts.sip_trunks.delete(
        sip_trunk_id="sip_trunk_id",
        account_id="account_id",
    )
    ```
  </Accordion>

  <Accordion title="Analytik">
    ### Nutzungsanalytik abrufen

    ```python theme={null}
    response = client.accounts.analytics.get_usage(
        account_id="account_id",
    )
    print(response.meta)
    ```
  </Accordion>

  <Accordion title="Subaccounts">
    ### Subaccounts auflisten

    ```python theme={null}
    subaccounts = client.accounts.subaccounts.list(
        account_id="account_id",
    )
    print(subaccounts.count)
    ```

    ### Subaccount erstellen

    ```python theme={null}
    account = client.accounts.subaccounts.create(
        account_id="account_id",
        name="name",
    )
    print(account.id)
    ```

    ### Subaccount abrufen

    ```python theme={null}
    account = client.accounts.subaccounts.retrieve(
        subaccount_id="subaccount_id",
        account_id="account_id",
    )
    print(account.id)
    ```

    ### Subaccount aktualisieren

    ```python theme={null}
    account = client.accounts.subaccounts.update(
        subaccount_id="subaccount_id",
        account_id="account_id",
    )
    print(account.id)
    ```
  </Accordion>
</AccordionGroup>

***

## Fehlerbehandlung

```python theme={null}
from itellicoai import Itellicoai
import itellicoai

client = Itellicoai(api_key="your-api-key")

try:
    agent = client.agents.retrieve("agent_123abc", account_id="account_id")
except itellicoai.AuthenticationError:
    print("Invalid API key")
except itellicoai.NotFoundError:
    print("Agent not found")
except itellicoai.RateLimitError:
    print("Rate limit exceeded")
except itellicoai.APIStatusError as e:
    print(f"API error: {e.status_code}")
```

***

## Umgebungsvariablen

```python theme={null}
import os
from itellicoai import Itellicoai

# API key automatically loaded from ITELLICOAI_API_KEY env var
client = Itellicoai()

# Or set explicitly
client = Itellicoai(api_key=os.getenv("ITELLICOAI_API_KEY"))
```

***

## Ressourcen

<CardGroup cols={2}>
  <Card title="PyPI-Paket" icon="python" href="https://pypi.org/project/itellicoai/">
    Von PyPI installieren
  </Card>

  <Card title="GitHub-Repository" icon="github" href="https://github.com/itellicoAI/server-sdk-python">
    Quellcode auf GitHub ansehen
  </Card>

  <Card title="API-Referenz" icon="book" href="/de/api-reference/introduction">
    REST-API-Dokumentation durchsuchen
  </Card>
</CardGroup>