How many companies in our model have more than 500 employees and are headquartered in the US?
What the agent does:
cargo-ai storage model list — finds the Companies model’s dataset and model slugs
cargo-ai storage model get-ddl <uuid> — gets the exact column names and types
Composes and executes a SQL query
# Step 1: Get the DDL for the exact column names and typescargo-ai storage model get-ddl <model-uuid># → {"ddl":"CREATE TABLE `datasets_default.models_companies` (name STRING, domain STRING, employee_count INT64, country STRING, ...)"}# Step 2: Reference the model logically as <dataset-slug>.<model-slug>cargo-ai storage query execute \ "SELECT COUNT(*) as total FROM default.companies WHERE employee_count > 500 AND country = 'US'"# → {"outcome":"queried","rows":[{"total":142}]}
In storage query, reference models as <dataset-slug>.<model-slug> (e.g.
default.companies) — not the physical datasets_…/models_… name. Run
model get-ddl first to confirm the available columns and types.
This example builds a workflow imperatively — assembling a raw node graph and
validating it with node validate. For a versioned, reviewable workflow,
author it declaratively instead with
defineWorkflow in a CDK workspace and ship it with
cargo-ai cdk deploy. Use this imperative path for one-off or
agent-constructed graphs.
Prompt:
Build a workflow that enriches company domains with Clearbit and writes the results back to the Companies model.
What the agent does:
cargo-ai connection connector list --integration-slug clearbit — finds connectorUuid
cargo-ai connection integration get clearbit — gets available actionSlug values and their config schemas (via manifest.actions.<actionSlug>.config.jsonSchema)
cargo-ai storage model list — finds the Companies model UUID
Assembles and validates a node graph, then executes
Create a lead scoring agent using GPT-4o-mini with a temperature of 0.0, focused on ICP fit.
What the agent does:
cargo-ai ai agent create — creates the agent resource
cargo-ai ai release get-draft — fetches the editable draft
cargo-ai ai release update-draft — sets model, prompt, temperature
cargo-ai ai release deploy-draft — publishes the configuration
# Step 1: Create the agentcargo-ai ai agent create \ --name "ICP Lead Scorer" \ --icon-color green \ --icon-face "📊" \ --description "Scores leads based on ICP fit from 1 to 10"# → {"agent":{"uuid":"agent-uuid",...}}# Step 2: Get the draftcargo-ai ai release get-draft --agent-uuid <agent-uuid># Step 3: Update draft configcargo-ai ai release update-draft --agent-uuid <agent-uuid> \ --system-prompt "You are a B2B lead scoring assistant. Given a company's profile, score its fit with our ICP from 1 to 10 and explain your reasoning in 2 sentences." \ --language-model-slug gpt-4o-mini \ --temperature 0.0 \ --max-steps 5# Step 4: Deploycargo-ai ai release deploy-draft --agent-uuid <agent-uuid> \ --integration-slug openai \ --language-model-slug gpt-4o-mini \ --actions '[]' \ --mcp-clients '[]' \ --resources '[]' \ --capabilities '[]' \ --suggested-actions '[]' \ --description "Initial deployment — ICP scorer v1"
Ask the lead researcher agent to find the VP of Sales at Acme Corp.
# 1. Find the agentcargo-ai ai agent list# → [{"uuid":"agent-uuid","name":"Lead Researcher"}]# 2. Create a chat sessioncargo-ai ai chat create \ --trigger '{"type":"draft"}' \ --agent-uuid <agent-uuid> \ --name "Acme research"# → {"chat":{"uuid":"chat-uuid",...}}# 3. Send a messagecargo-ai ai message create \ --chat-uuid <chat-uuid> \ --parts '[{"type":"text","text":"Find the VP of Sales at Acme Corp and their LinkedIn URL."}]'# → {"userMessage":{"uuid":"..."},"assistantMessage":{"uuid":"assistant-msg-uuid","status":"pending"}}# 4. Poll for the response (every 2 seconds)cargo-ai ai message get <assistant-msg-uuid># → Terminal when status is "success" — read .message.parts[].text# 5. Continue the conversation (context is preserved in the chat)cargo-ai ai message create \ --chat-uuid <chat-uuid> \ --parts '[{"type":"text","text":"Now find their email address."}]'
Run cargo-ai whoami and share the output with your agent if it seems confused about which workspace to target. If you work across multiple workspaces, make the active one explicit with export CARGO_WORKSPACE_UUID=<uuid>.
Front-load context about your workspace
Start a session by telling your agent what exists: “I have Companies and
Contacts models, a HubSpot connector, and a lead enrichment tool called
‘Enrich from Clearbit’.” This lets the agent confirm UUIDs rather than
guessing, and saves multiple discovery round-trips.
Get the DDL before any SQL query
The table name for a Cargo model is not guessable. Always run storage model get-ddl <uuid> before writing queries. The DDL includes the exact table name (e.g., datasets_default.models_companies) and every column’s type.
Ramp batch sizes gradually
Start every new workflow with 1 record, then 50, then 500, before running on
your full segment. This surfaces connector rate limit issues before they
affect thousands of records. Only connector nodes (kind: "connector") have
rate limits — native nodes do not.
Always inspect failedRunsCount after a batch
A batch reporting status: "success" can still have individual run failures. Check failedRunsCount in batch get, download failures with run download --statuses error, and re-queue with batch create --data '{"kind":"recordIds","recordIds":[...]}'.
Keep a .cargo-context.md for repeat tasks
For frequently used workflows or segments, note their UUIDs in a .cargo-context.md in your project root. Your agent will use them directly instead of re-running discovery commands every session.
For quick runs (single records, small batches under 100 records), --wait-until-finished is the simplest pattern. For large batches (1000+ records), poll manually with batch get so your agent can report incremental progress without a timeout.
