One Agent call mode

Call mode is what one-agent does when a task says nothing about looping. It answers once with the contract of llm-agent: any provider and model, a persona or skill, conversation history, streaming, and a choice of response format.

A first call

curl -s -X POST https://api.plungeai.com/v1/agents/one-agent/execute \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"prompt":"In one sentence: what is a content delivery network?","sync":true,"max_tokens":60}'

The answer is in content. The request fields are listed on Execute an agent.

Fields

Field	Type	Meaning
`prompt` (alias `input`)	string	The question or instruction. Required unless `messages` has a user turn.
`messages`	array	Prior chat turns `[{role, content}]`; the model answers from the whole conversation.
`system`	string	System prompt.
`provider`, `model`	string	Pin a provider and model. Send them together; the model is checked against the catalog. The default provider is `gemini`.
`persona`	string	A persona id. It is the only capability field the agents plane forwards.
`max_tokens`	number	Output cap.
`temperature`, `top_p`, `reasoning_effort`, `thinking_level`		Sampling and reasoning hints forwarded to the model.
`stream`	boolean	`true` returns an OpenAI-shaped stream that ends with `data: [DONE]`.
`sync`	boolean	Default `true`. `false` returns a `202` pointer; redeem it with `GET /v1/agents/results/{workflowId}/{taskId}`.
`format`	string	`json`, `yaml`, `markdown` or `text` (see Four wires).
`user_context`	object	The caller's time zone, locale and place. Default: derived from the request's network location.

A persona, skill or expert id is resolved by the same capability layer that serves bots and missions, so one id means the same thing everywhere.

Conversation

messages carries a conversation inside one call.
In a workflow task, memory: true with a memory_scope loads the stored conversation history for that scope.
A task with session_id and a new prompt continues a stored session. Over MCP, plungeai_execute_agent takes session_id and plungeai_continue answers a pause.
A call with nothing to answer is refused with needs_input rather than sent to the model.

In a workflow task

A type: task step with agent: one-agent takes the same fields, and also skill or skills, expert or experts, and memory: true. Send it to POST /v1/workflows/execute with Content-Type: text/yaml:

workflow:
  name: skill-demo
  tasks:
    - id: assess
      type: task
      agent: one-agent
      prompt: "Assess a company with revenue 120M (+18% YoY), gross margin 72%, operating margin -4%, cash 80M, burn 15M per year. Three sentences."
      skill: financial-analysis
      maxTokens: 200

The answer comes back as content of the final task, in the wire you sent (YAML in, YAML out; see Four wires).

Answer as a persona

curl -s -X POST https://api.plungeai.com/v1/agents/one-agent/execute \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"prompt":"Index fund or individual stocks for a 30-year-old? Two sentences.","persona":"warren-buffett","max_tokens":120}'

Need tools or more than one turn?

Add a loop command and the same id runs loop mode.