firetiger-create-agent

Firetiger Create Agent

Firetiger agents autonomously analyze telemetry, detect anomalies, investigate issues, and take actions through connections (Slack, GitHub, Linear, databases, …). Three ways to get one — prefer a goal or a catalog template over hand-building.

Quick Start

create_agent_with_goal with:
  goal: "Monitor Next.js API routes for errors and slow responses; alert on error-rate spikes and p95 latency increases"
  title: "Checkout Health Monitor"   # optional

The agent-planner (a system agent, agents/agent-planner) configures the prompt, connections, and triggers from the goal, then returns the planner conversation. If the planner asked a question, you must answer it or the agent won't finish — reply with send_agent_message on the plan session.

Path A (recommended): create from a goal

Call create_agent_with_goal with a clear goal (optional title, agent_id, wait_for_plan default true).
Handle planner questions. The planner asks sparingly ("act first, refine later"), via a request_user_input. Answer on the user's behalf from the codebase/context — or ask the user if genuinely unknown — by writing to the plan session:
```
send_agent_message with session: "<plan_session from the tool output>"
  message: "Monitor the Postgres connection at DATABASE_URL; alert threshold p99 > 500ms."
```
Confirm. When the planner completes, the agent flips to AGENT_STATE_ON. Share its name and focus.

Example goals

"Monitor Next.js API routes for errors and slow responses"
"Track database query latency and alert if p99 exceeds 500ms"
"Watch for deployment failures and notify on Slack"
"Track error rates across all services and open issues for spikes"

Path B: install a prebuilt catalog agent

Firetiger ships tuned templates for common stacks. Browse and install them:

list with resource: "catalog-agents"
create with resource: "catalog-agents/{catalog-agent}/..."   # or the InstallCatalogAgent flow

Templates include postgres-performance, postgres-schema, mysql-performance, mysql-schema, clickhouse-performance, temporal-performance, aws-cost-optimizer, and datadog-cost-expert.

Key gotcha: an installed catalog agent starts in AGENT_STATE_RECOMMENDED, not ON — it won't run until a human turns it on. Send it a direct message (or set state: AGENT_STATE_ON) to activate.

Path C: configure manually

Use the generic CRUD tools when you need explicit control. Always run schema first — fields drift.

schema with collection: "agents"

Agent fields worth knowing: title, description, prompt (guides every session), state, connections[] ({name: "connections/{id}", enabled_tools: [...]} — what external tools the agent may use), mcp_connections[] (external MCP servers), tags[], expire_time (auto-archive after), cache_ttl (CACHE_TTL_5M / CACHE_TTL_1H), network_profile. skills and plan_session are output-only.

state (AgentState) values: AGENT_STATE_ON, AGENT_STATE_OFF, AGENT_STATE_RECOMMENDED, AGENT_STATE_REVIEW_REQUIRED, AGENT_STATE_UNSPECIFIED. Only an ON agent fires from triggers or schedules.

create with resource: "agents"
  body: { "title": "Checkout Health Monitor",
          "description": "Daily health analysis of checkout",
          "prompt": "You are a daily health check agent...",
          "connections": [{"name": "connections/slack-prod", "enabled_tools": ["post_message"]}],
          "state": "AGENT_STATE_ON" }

Triggers — how agents fire (six kinds)

Triggers are separate resources (triggers/{id}) referencing an agent. InvokeTrigger and automatic firing require the target agent be AGENT_STATE_ON. Common fields: display_name, agent (required, agents/{id}), enabled, associated_resources, and one configuration:

Config	Fires when	Key fields
`cron`	On a recurring schedule	`schedule` (5-field cron), `timezone` (IANA, default UTC)
`manual`	On `InvokeTrigger` or a POST to its webhook	`webhook_token`, `webhook_address` (output-only)
`post_deploy`	Once when a SHA (or descendant) deploys	`repository`, `environment`, `sha`, `delay`
`row`	When a matching row lands in a table	`table_name`, `predicate` (SQL), `cooldown` (default 15m)
`slack_message_posted`	On messages in Slack channels	`slack_connection`, `channels[]`, `include_thread_replies`
`slack_agent_mentioned`	When the agent's Slack handle is mentioned	`slack_handle`, `channels[]`

Cron example:

create with resource: "triggers"
  body: { "display_name": "Daily Checkout Health Check",
          "agent": "agents/{agent-id}", "enabled": true,
          "configuration": { "cron": { "schedule": "0 9 * * *", "timezone": "America/Los_Angeles" } } }

Scheduled agent runs — one-shot, not cron

scheduled-agent-runs are single deferred invocations ("run this prompt on agent X in 1 hour"), not recurring schedules. Fields: agent_id, prompt, time_delta (delay from now), plus use_latest_session / incognito; scheduled_time and has_run are output-only. For anything recurring, use a cron trigger.

Writing good agent prompts

Specific, scoped, actionable — and say what the agent should NOT do.

You are a daily health check agent for the checkout service.

Your job:
1. Query the last 24 hours of traces for checkout.
2. Calculate error rates and p99 latency; compare to the previous 24h.
3. If error rate rose >10% or p99 >20%, open an issue.
4. Summarize findings briefly.

Focus only on checkout. Do not investigate other services.

Common Mistakes

#	Mistake	Fix
1	Ignoring the planner's question	`create_agent_with_goal` isn't done until you answer via `send_agent_message` on the plan session.
2	Expecting a catalog agent to run immediately	It installs as `AGENT_STATE_RECOMMENDED` — turn it ON.
3	Trigger created but agent is OFF	Firing requires `AGENT_STATE_ON`.
4	Using `scheduled-agent-runs` for recurring work	Those are one-shot — use a `cron` trigger for recurrence.
5	Manual `create` without `schema`	Field names drift — call `schema` for `agents`/`triggers` first.
6	Embedding the trigger in the agent	Triggers are separate resources referencing `agents/{id}`.
7	Unbounded prompt	State what the agent should NOT do; scope it to specific services.

Run and steer an existing agent's session: firetiger-monitor-deploy.
Manual investigations and the issues agents open: firetiger-investigate.
Connect the integrations an agent acts through: firetiger-setup.

About this skill