---
title: "Launch Research Agent"
url: "https://docs.caracal.run/examples/research-agent/"
markdown_url: "https://docs.caracal.run/markdown/examples/research-agent.md"
description: "Run a plain CLI agent with Google and OpenAI provider credentials injected by caracal run."
page_type: "workflow"
concepts: []
requires: []
---

# Launch Research Agent

Canonical URL: https://docs.caracal.run/examples/research-agent/
Markdown URL: https://docs.caracal.run/markdown/examples/research-agent.md
Description: Run a plain CLI agent with Google and OpenAI provider credentials injected by caracal run.
Page type: workflow
Concepts: none
Requires: none

---

Research Agent is a `caracal run` example under `examples/ResearchAgent`. It launches a normal Node.js CLI agent and injects provider-native credentials only into the child process after Caracal authorizes the run.

## What it demonstrates

| Resource | Injected env | Used for |
| --- | --- | --- |
| `resource://google-drive` | `GOOGLE_DRIVE_ACCESS_TOKEN` | Searching and exporting Google Drive documents. |
| `resource://google-calendar` | `GOOGLE_CALENDAR_ACCESS_TOKEN` | Reading relevant Calendar events. |
| `resource://openai` | `OPENAI_API_KEY` | Answering the terminal question with model context. |

The agent has no Caracal SDK dependency. It reads provider-native environment variables and behaves like an existing third-party terminal tool.

## Console setup

Use Console to create or select:

| Object | Purpose |
| --- | --- |
| Zone | Owns the application, providers, resources, and policies. |
| Application | Workload identity used by `caracal run` to call STS. |
| Google Drive provider | Returns a Drive read token. |
| Google Calendar provider | Returns a Calendar read token. |
| OpenAI provider | Returns an OpenAI-compatible credential. |
| Resources | Map `resource://google-drive`, `resource://google-calendar`, and `resource://openai` to providers. |
| Policy | Allows the run application to request all three resources. |

Enable runtime injection on each provider and map each run credential with `credential_type = "provider_token"`.

## Write the runtime profile

Use Console-generated values for the zone id and application id. Store the one-time application secret in the local runtime secret path and write a `caracal.toml` profile:

```toml
zone_id = "zone_prod"
application_id = "app_support_research_agent"
ttl_seconds = 900
continue_on_failure = false

[[credentials]]
env = "GOOGLE_DRIVE_ACCESS_TOKEN"
resource = "resource://google-drive"
credential_type = "provider_token"

[[credentials]]
env = "GOOGLE_CALENDAR_ACCESS_TOKEN"
resource = "resource://google-calendar"
credential_type = "provider_token"

[[credentials]]
env = "OPENAI_API_KEY"
resource = "resource://openai"
credential_type = "provider_token"
```

Do not export `GOOGLE_DRIVE_ACCESS_TOKEN`, `GOOGLE_CALENDAR_ACCESS_TOKEN`, or `OPENAI_API_KEY` yourself. Caracal injects them into the child process after STS authorization.

## Launch the agent

```bash
cd examples/ResearchAgent
export CARACAL_CONFIG="$HOME/.config/caracal/research-agent/caracal.toml"
caracal run -- node agent.mjs
```

The agent confirms the injected credentials (values masked) and opens an interactive prompt:

```text
[agent] credential preflight (values masked, injected by launcher):
[agent]   GOOGLE_DRIVE_ACCESS_TOKEN  present  -> Google Drive (read-only scope)
[agent]   GOOGLE_CALENDAR_ACCESS_TOKEN  present  -> Google Calendar (read-only scope)
[agent]   OPENAI_API_KEY  present  -> OpenAI
Caracal run research agent ready. Ask about Drive docs or Calendar events. Type "exit" to quit.
>
```

Started directly with `node agent.mjs`, the preflight fails with exit code 2 before any network call. Credentials disappear with the child-process environment when the process exits.

## Test

```bash
cd examples/ResearchAgent
pnpm test
```

The tests do not contact Google, OpenAI, or Caracal.

## Next step

Continue to [Run Lynx Capital](/examples/lynx-capital/) when you want a full app reference lab with live Console inspection.