Talking to agents

Chat with an agent belongs to signed-in members, on the agent’s page in the app. An organization key cannot open an agent’s chat. From code, you reach an agent through a workflow: an Agent step runs the agent with a task, and you start that workflow through the API. It is the same agent, with the same instructions, model and grants, as the one members chat with.

Set up a workflow for the agent

Create the agent on the Agents page and grant it the apps, skills and databases it needs. See Creating an agent.
Create a workflow with a Trigger and an Agent step after it.
In the Agent step, pick the agent and write its Task. Use the payload you will send, for example Answer this question: {{ trigger.question }}.
Press Publish.

If the Task is empty, the agent receives the text of the step before it. For a step right after the Trigger, that is the raw input you send. See Agents in workflows.

An Agent step is told it runs unattended. The agent does not ask questions, since no one answers them during a run. It does what the task allows and says in its reply what it assumed.

Ask the agent

Start the workflow with your question in input:

curl -X POST https://superflows.app/api/v1/workflows/WORKFLOW_ID/runs \
  -H "Authorization: Bearer sf_..." \
  -H "Content-Type: application/json" \
  -d '{"input": "{\"question\": \"Which open issues mention the billing page?\"}"}'

Then poll GET /api/v1/runs/{id} until status is complete, errored or terminated. See Starting runs for the run’s fields.

Read the answer

When the Agent step is the last step, the run’s reply is the agent’s answer. The Agent step’s entry in steps also holds its output:

Field	What it holds
`response`	The agent’s reply
`thread`	The id of the thread the run started on the agent
`tools`	One line per tool call: the tool and `ok`, or the tool and its error
`approvals`	JSON text listing the app actions a member approved or denied during the run

Each run starts a new thread on the agent, titled after the workflow and the run. Members can read it on the agent’s Chat tab at https://superflows.app/app/agents/<agent id>?thread=<thread id>.

Decide approvals from code

When the agent calls an action its grant marks as ask first, the call waits for a decision. The Agent step’s status becomes waiting, and its output.approvals is JSON text listing each call with its id, tool, input and a status of pending. Admins are emailed a link to the run.

Any member can decide on the run page or in the agent’s chat. Your code can decide too:

curl -X POST https://superflows.app/api/v1/runs/RUN_ID/approvals/APPROVAL_ID \
  -H "Authorization: Bearer sf_..." \
  -H "Content-Type: application/json" \
  -d '{"decision": "deny", "reason": "Not during the freeze"}'

Field	Type	What it does
`decision`	`approve` or `deny`	Approving runs the action. Denying tells the agent no
`reason`	string, up to 1,000 chars	Optional. On a denial, the agent receives it as the reason

The run continues either way. A call nobody decides within 72 hours is denied, and the Agent step fails with a message that the approval expired without a decision.

Status	Code	Meaning
404	`run_not_found`	No run with that id in your organization
404	`approval_not_found`	No waiting Agent step asked for that approval
409	`approval_not_pending`	Someone already decided it

Manage agents with a key

A key can list, create, read, update and delete the organization’s agents:

Method and path	Does
`GET /api/v1/agents`	Lists agents, newest first, with paging
`POST /api/v1/agents`	Creates an agent
`GET /api/v1/agents/{id}`	Reads one agent
`PATCH /api/v1/agents/{id}`	Changes the fields you send
`DELETE /api/v1/agents/{id}`	Deletes the agent and its threads

curl -X POST https://superflows.app/api/v1/agents \
  -H "Authorization: Bearer sf_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "issue-reader", "description": "Answers questions about open issues", "instructions": "Answer from the issues you can read. Say when you are unsure."}'

Only name is required: lowercase letters, numbers and single hyphens, up to 64 characters, unique in the organization. Fields you leave out take their defaults: Vercel AI Gateway with its default model, medium thinking, and no apps, skills or databases granted. A second agent with the same name answers 409 agent_name_taken. Past your plan’s agent cap, creating one answers 402 plan_limit_reached.

Skills work the same way, at /api/v1/skills and /api/v1/skills/{id}. A skill created with a key belongs to the organization. See Skills.