---
name: bijection-agents
description: "Evaluate and integrate the AI Agent component with Bijection."
---

# AI Agent

Agent threads, tools and streaming

- Package: @bijectionhq/agents
- Category: AI & Agents
- Status: Included
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/agents/tree/8598acb6eeab2b2f76ac99feb4abcc3e66602de9
- Upstream: https://github.com/convex/agent/tree/d143f27c0dc1ce7269db38cf8d450e85a39e186f
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/agents

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/agents.git
cd agents
git checkout 8598acb6eeab2b2f76ac99feb4abcc3e66602de9
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This source is included in Bijection's workspace. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes @convex-dev/agent. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


> Agents: read this skill fully before writing code that uses AI Agent. Follow the installation and configuration steps exactly.

# AI Agent

## Instructions

The AI Agent component provides a structured framework for building agentic AI workflows with persistent message threads, automatic conversation context, and vector search capabilities. It separates long-running AI operations from your UI while maintaining real-time reactivity through Convex's websocket streaming. The component handles thread management, message persistence, file storage integration, and includes built-in debugging tools and usage tracking.

### Installation

```bash
npm install @convex-dev/agent
```

Current npm version: `@convex-dev/agent@0.7.8`

## Use cases

- Building customer support chatbots that need to maintain conversation history across multiple sessions and agents
- Creating multi-step AI workflows where different agents handle specific tasks like research, analysis, and reporting
- Implementing collaborative AI assistants where human agents and AI agents work together in shared threads
- Developing AI-powered applications that require RAG capabilities with hybrid vector and text search across conversation history
- Building usage-metered AI services that need per-user, per-agent cost tracking and rate limiting

## How it works

The component centers around Agents, Threads, and Messages as core abstractions. Agents encapsulate LLM prompting logic, tools, and behavior, while Threads persist conversation history that can be shared across multiple users and agents. Messages automatically include conversation context through built-in hybrid vector/text search within threads.

Streaming is handled through Convex's websocket infrastructure, enabling real-time text and object streaming without HTTP streaming complications. The component integrates with Convex file storage for automatic file handling with reference counting, and supports both static and dynamic workflows for complex multi-agent operations.

Debugging capabilities include callback functions, an agent playground for prompt iteration, and dashboard inspection. Usage tracking provides granular metrics per-provider, per-model, and per-user, while rate limiting integration helps manage API costs and provider limits.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by AI Agent is not needed

## Resources

- [npm package](https://www.npmjs.com/package/%40convex-dev%2Fagent)
- [GitHub repository](https://github.com/get-convex/agent)
- [Live demo](https://docs.convex.dev/agents)
- [Convex Components Directory](https://www.convex.dev/components/agent)
- [Convex documentation](https://docs.convex.dev)