Integrating CrewAI with Fikra API

CrewAI supports OpenAI-compatible interfaces. Since Fikra API exposes an OpenAI-style chat-completions endpoint, you can configure CrewAI to use Fikra models by pointing the underlying LLM client to the Fikra base URL and providing a Fikra API key.

Prerequisites

• A Fikra account with an active API key (fk_live_...).
• Python 3.9+.
• crewai and openai Python packages installed.
• Access to the Fikra dashboard to verify your token-credit wallet balance.

Environment Variable Setup

Store your Fikra API key in an environment variable to avoid hardcoding secrets.

export FIKRA_API_KEY="fk_live_your_key_here"

Python Example

The following example configures CrewAI to use the fikra-flash model via the OpenAI-compatible interface.

import os
from crewai import Agent, Task, Crew
from crewai.tools import Tool
from openai import OpenAI

# Initialize an OpenAI client pointing to Fikra API
client = OpenAI(
    base_url="https://api.fikraapi.co.ke/v1",
    api_key=os.environ["FIKRA_API_KEY"]
)

# Define an agent using the Fikra model
# Note: CrewAI's LLM configuration may vary by version. 
# Ensure your CrewAI version supports custom base_url for OpenAI-compatible providers.
# If direct OpenAI client injection is not supported in your CrewAI version,
# you may need to use a wrapper or check the latest CrewAI documentation for 
# OpenAI-compatible provider configuration.

# Example of a simple agent setup (adjust based on your CrewAI version's API)
# This is a conceptual example. Verify with your specific CrewAI version.

# For direct API calls without CrewAI abstraction:
response = client.chat.completions.create(
    model="fikra-flash",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello, Fikra!"}
    ]
)

print(response.choices[0].message.content)

Note: CrewAI's internal LLM abstraction may require specific configuration for non-OpenAI providers. If the standard OpenAI client injection does not work directly with your CrewAI version, refer to CrewAI's documentation for configuring custom LLM providers or use the raw openai client for direct API calls as shown above.

Streaming Guidance

Fikra API supports streaming via Server-Sent Events (SSE) when stream: true is set.

stream = client.chat.completions.create(
    model="fikra-flash",
    messages=[
        {"role": "user", "content": "Explain quantum computing in simple terms."}
    ],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

Common Errors

• 400 Bad Request: Malformed request body, invalid model alias, or missing required fields. Verify that the model field uses a valid Fikra alias (e.g., fikra-flash) and that the JSON structure matches OpenAI chat-completions format.
• 401 Unauthorized: Invalid or missing API key. Ensure the Authorization: Bearer fk_live_... header is correctly set and the key is active in the Fikra dashboard.
• 402 Payment Required: Insufficient token-credit balance. Top up your wallet via the Fikra dashboard using M-Pesa or card payment.
• 429 Too Many Requests: Rate limit exceeded. Unverified accounts are limited to 30 RPM; trusted accounts to 100 RPM. Implement exponential backoff and retry logic.
• 503 Service Unavailable: Temporary server-side issue. Retry with backoff. If persistent, check the Fikra dashboard for status updates.

Production Checklist

• [ ] Use environment variables for API keys; never hardcode secrets.
• [ ] Implement retry logic with exponential backoff for 429 and 503 errors.
• [ ] Monitor token-credit balance to avoid 402 errors.
• [ ] Validate model aliases against the Fikra model registry before deployment.
• [ ] Test streaming behavior in staging to ensure SSE handling is robust.
• [ ] Log request IDs and error codes for debugging.
• [ ] Verify rate limits (30 RPM unverified, 100 RPM trusted) and design accordingly.
• [ ] Keep dependencies (crewai, openai) up to date for compatibility.