Skip to content

Add CrewAI BYO Agent docs #238

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
peterj merged 2 commits into from
Oct 1, 2025
Merged

Add CrewAI BYO Agent docs #238

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4a6b577
docs: crewai byo docs
supreme-gg-gg Sep 30, 2025
5288625
docs: add serper desc
supreme-gg-gg Oct 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
257 changes: 257 additions & 0 deletions src/app/docs/kagent/examples/crewai-byo/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,257 @@
---
title: "BYO CrewAI Agents"
pageOrder: 1
description: "Bring your own CrewAI agent to kagent"
---

export const metadata = {
title: "Bringing your own CrewAI agent to kagent",
description: "Learn how to bring your own CrewAI agent to kagent",
author: "kagent.dev",
};

# Bringing your own CrewAI agent to kagent

Bring your own custom agents. This example uses [CrewAI](https://www.crewai.com/), but you can also try out the [ADK guide](/docs/kagent/examples/a2a-byo/) or [LangGraph guide](/docs/kagent/examples/langchain-byo/). Such frameworks give you more control over the agent behavior and are well-suited for complex workflows and integration with external systems and APIs.

Unlike declarative agents that are defined by kagent resources with components such as system instructions, models, and tools written inline, these BYO agents give you full control over agent logic. If you have your own agent, no need to decompose its functions into separate kagent resources. Kagent can invoke your agent directly through the A2A protocol.

## Prerequisites

Install kagent by following the [quick start](/docs/kagent/getting-started/quickstart) guide.

## Building a custom agent

The following example builds a research crew agent from the [kagent code repository](https://github.com/kagent-dev/kagent). The sample app is built with CrewAI framework and performs research tasks using web search capabilities. It uses OpenAI's GPT models as the underlying LLM provider and Serper for web search.

1. Clone the kagent code repository.

```bash
git clone https://github.com/kagent-dev/kagent.git
cd kagent
```

2. Optional: If you do not have a Docker registry, you can use the `make helm-install` command to create one as part of installing kagent in your kind cluster.

3. Build the custom agent image and push it to your local Docker registry.

```bash
cd python/samples/crewai/research-crew
docker build . -t localhost:5001/research-crew:latest --push
```

### Adapting your own CrewAI agent

A quickstart and detailed guide for adapting existing CrewAI crews and flows to work with KAgent is available in the [package's README](https://github.com/kagent-dev/kagent/tree/main/python/packages/kagent-crewai).
This provides a simple way to setup A2A server, tracing, and session-aware memory and state persistence.

Two complete examples are available in the `python/samples/crewai/` directory:

- [**Crew Example**](https://github.com/kagent-dev/kagent/tree/main/python/samples/crewai/research-crew): A multi-agent crew for web research and analysis
- [**Flow Example**](https://github.com/kagent-dev/kagent/tree/main/python/samples/crewai/poem_flow): A CrewAI flow that generates and continues poems

## Creating a BYO Agent resource

Now that you have your own custom agent image, you can create a BYO Agent resource for kagent to manage.
You will need a Serper API Key that you can get for free [from their website](https://serper.dev). Serper is a Google Search API used by most CrewAI examples and tutorials, but you can also plug in your own tools.

1. Save the API keys for your LLM provider and web search service in environment variables.

```bash
export OPENAI_API_KEY=your-openai-api-key-here
export SERPER_API_KEY=your-serper-api-key-here
Comment thread
peterj marked this conversation as resolved.
```

2. Create secrets with the API keys.

```bash
kubectl create secret generic kagent-openai -n kagent \
--from-literal=OPENAI_API_KEY=$OPENAI_API_KEY \
--dry-run=client -o yaml | kubectl apply -f -

kubectl create secret generic kagent-serper -n kagent \
--from-literal=SERPER_API_KEY=$SERPER_API_KEY \
--dry-run=client -o yaml | kubectl apply -f -
```

3. Create a BYO Agent resource.

```yaml
kubectl apply -f - <<EOF
apiVersion: kagent.dev/v1alpha2
kind: Agent
metadata:
name: research-crew
namespace: kagent
spec:
description: A research crew with multiple specialized agents for web research and analysis.
type: BYO
byo:
deployment:
image: localhost:5001/research-crew:latest
env:
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: kagent-openai
key: OPENAI_API_KEY
- name: SERPER_API_KEY
valueFrom:
secretKeyRef:
name: kagent-serper
key: SERPER_API_KEY
EOF
```

## Testing the A2A endpoint

The A2A endpoint is exposed on the port `8083` of the kagent controller service.

1. Enable port-forwarding on the `kagent-controller` service.

> Note that you could also expose the A2A endpoint publicly by using a gateway.

```bash
kubectl port-forward svc/kagent-controller 8083:8083 -n kagent
```

2. To test that the agent is available and has an agent card, send a request to the `.well-known/agent.json` endpoint. Note the API endpoint follows the pattern `/api/a2a/{namespace}/{agent-name}/.well-known/agent.json`.

```bash
curl localhost:8083/api/a2a/kagent/research-crew/.well-known/agent.json
```

Example output: This JSON object describes the agent as per the [A2A protocol](https://a2a.guide/protocol/agent-card.html).

```json
{
"name": "research_crew",
"description": "A research crew with multiple specialized agents for web research and analysis.",
"url": "http://127.0.0.1:8083/api/a2a/kagent/research-crew/",
"version": "",
"capabilities": {
"streaming": true,
"pushNotifications": false,
"stateTransitionHistory": true
},
"defaultInputModes": ["text"],
"defaultOutputModes": ["text"],
"skills": []
}
```

## Invoking the agent

You can invoke the agent in several ways, including the kagent dashboard, kagent CLI, and the A2A host CLI.

### Dashboard

Launch the dashboard with `kagent dashboard`, find your `research-crew`, and start chatting. For complete steps, see the [Your First Agent](/docs/kagent/getting-started/first-agent) guide.

### kagent CLI

To use the kagent CLI, make sure that the controller is still being port-forwarded.

Then, use the invoke command. For more options, run `kagent help invoke`.

```shell
kagent invoke --agent research-crew --task "Research topics on AI reliability and provide a summary."
```

Example output: The output includes both the response as well as the details of the response. The formatting is in JSON but can be quite long, depending on the call and the agent configuration.

```json
{
"artifacts": [
{
"artifactId": "2d44a62e-d079-4dae-8ee8-f8759add9ffe",
"parts": [
{
"kind": "text",
"text": "After researching AI reliability, I found that it encompasses aspects like robustness, safety, and trustworthiness..."
}
]
}
],
...
}
```

### A2A host CLI

You can use the A2A host CLI to invoke the agent. This CLI is part of the [A2A samples repository](https://github.com/a2aproject/a2a-samples/tree/main/samples/python/hosts/cli).

1. Clone the A2A samples repository.

```bash
git clone https://github.com/a2aproject/a2a-samples.git
```

2. From the `a2a-samples/samples/python/hosts/cli` directory, point the CLI to the kagent endpoint.

```bash
cd a2a-samples/samples/python/hosts/cli
uv run . --agent http://127.0.0.1:8083/api/a2a/kagent/research-crew
```

Example output: The CLI connects to the kagent, displays the agent card and prompts you for input.

```console
======= Agent Card ========
{"capabilities":{"pushNotifications":false,"stateTransitionHistory":true,"streaming":true},"defaultInputModes":["text"],"defaultOutputModes":["text"],"description":"A research crew with multiple specialized agents for web research and analysis.","name":"research_crew","protocolVersion":"0.2.6","skills":[],"url":"http://127.0.0.1:8083/api/a2a/kagent/research-crew/","version":""}
========= starting a new task ========

What do you want to send to the agent? (:q or quit to exit):
```

3. Send the task `"Research topics on AI reliability and provide a summary."` to the agent. You'll be also prompted to optionally attach a file to the request, but just hit enter to skip this step.

Example output: You get a stream of events that include the prompt and the agent's response, such as the following.

```json
{
"contextId": "157a0834df2c459d9cee45316ffbfb5b",
"final": false,
"kind": "status-update",
"metadata": {
"crewai_app_name": "kagent__NS__research_crew",
"crewai_author": "research_agent",
"crewai_invocation_id": "e-8619b200-2f0a-4257-bd6b-b08bd1b139fd",
"crewai_session_id": "157a0834df2c459d9cee45316ffbfb5b",
"crewai_usage_metadata": {
"candidatesTokenCount": 150,
"candidatesTokensDetails": [
{
"modality": "TEXT",
"tokenCount": 150
}
],
"promptTokenCount": 500,
"promptTokensDetails": [
{
"modality": "TEXT",
"tokenCount": 500
}
],
"totalTokenCount": 650
},
"crewai_user_id": "admin@kagent.dev"
},
"status": {
"message": {
"kind": "message",
"messageId": "dd05c3cd-2dc3-4efd-9791-d7124be6dd52",
"parts": [
{
"kind": "text",
"text": "After researching AI reliability, I found that it encompasses aspects like robustness, safety, and trustworthiness..."
}
],
"role": "agent"
},
"state": "working",
"timestamp": "2025-08-14T22:15:04.276358+00:00"
},
"taskId": "59d2b071-04e9-4fef-a0dd-e925dd13cceb"
}
```