Launch Research Agent

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:

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

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:

[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

cd examples/ResearchAgent
pnpm test

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

Next step

Continue to Run Lynx Capital when you want a full app reference lab with live Console inspection.