Working effectively with io
Use this guide after choosing Console or the terminal. It covers describing a task, reviewing changes, handling incomplete work, and investigating an agent's behavior.
The card, editor, and chart descriptions below refer to Console. Follow the terminal guide for its picker, approval, and unattended-mode controls. For a task overview and prerequisites, see Getting started with io.
How io approaches your request
io can inspect agents, corpora, tools, enabled LLMs, and pipelines within your permissions, and consult the Vectara API specification and product documentation. Give it enough context to identify the target; a name may need clarification if it does not identify the intended resource.
Treat a generated configuration as a proposal to review, not as evidence that the workflow has been validated. The guidance below separates the request, the approval, and the resulting state.
In Console, a clarifying question can mark an option with a Recommended badge. No option is preselected. Click a choice to answer or use Write your own answer for a free-text response.
Write prompts that reduce follow-up questions
Say when you want defaults
Use just draft something or use defaults for everything when the scope is already bounded and you prefer to review a concrete draft. Review the assumptions along with the proposal.
Defaults do not define permitted actions for a high-stakes task or establish that the result is safe for production. See Where io stops.
Open the resource you mean
Console provides context about the resource you have open. Requests such as add a web search tool to it can use that context. Confirm that the proposal targets the intended resource.
Without an open resource, provide its name or key. io can inspect resources within your permissions without requiring you to open each one.
Name external targets explicitly
Give the domain, repository, or endpoint rather than referring only to "the docs", "the API", or "our wiki". This avoids leaving the intended system unspecified.
Specify the outcome, not the object
Naming the behavior and target makes a request actionable. It does not eliminate necessary clarification, discovery, or approval of separate changes.
| Underspecified request | More actionable request |
|---|---|
| Create an agent. | Create a support Q&A agent over the product-docs corpus. It should cite answers, say when it does not know, and escalate billing questions. |
| Connect it to my docs. | Use the documentation site at https://docs.example.com as the source, ingest it into a new corpus named product-docs, then create a Q&A agent over that corpus. |
| Add a tool for our API. | Create a tool for GET https://api.example.com/customers/{id} using an API key stored as agent.secrets.customer_api_key, then attach it to the support agent. |
| Make it better. | Review the support-bot agent for citation behavior, retrieval configuration, tool access, and fallback instructions, then propose only the highest-impact fixes. |
| Why did it fail? | Diagnose session <session_key> for agent <agent_key>. Summarize the failing step, the tool error if there was one, and what the model saw before the failure. |
From your request to a created resource
Use this sequence to track the task. Resource inspection does not need a change-approval card; a proposed change does need review.
| Phase | What to establish | What to check |
|---|---|---|
| Discover | Identify the relevant resources. | The intended account, names, and keys. |
| Ground | Consult the API specification and relevant guidance. | The operation and proposed fields. |
| Decide | Resolve choices that discovery cannot settle. | The scope and assumptions. |
| Propose | Inspect the proposed request. | Review, edit where supported, then accept or cancel. |
| Execute | Apply the approved request. | Approval is not evidence that the API request succeeded. |
| Verify | Inspect the resulting resource. | The returned key and resulting configuration. |
Your approval defines the intended change. The first attempt should use the approved body, including your edits rather than a merge with the original proposal. Recovery can involve the constrained corrections described below; do not assume every retry has an identical body.
Expect separate proposals for separate changes. A task may involve a corpus, an agent, a pipeline, and successive updates. Review the target and operation each time rather than relying on a fixed number of cards.
When a write fails
Distinguish a mechanical correction from a new decision. A validation failure may be recoverable by consulting the specification and correcting field names or request structure within the approved change set. Substituting a different LLM, changing the target, or supplying missing credentials is not just a formatting correction: review that decision.
For a create conflict, inspect the existing resource before deciding to change it. A verified match can satisfy the requested outcome; a different configuration needs a decision rather than a silent overwrite.
Review the reported outcome and current configuration after recovery. Missing resources, permissions, or credentials require attention rather than repeated approval of the same unsuccessful proposal.
Check progress before continuing
If work stops partway through, ask io to separate confirmed resources and their keys from failed or pending operations and remaining setup. Check the current resources before continuing; a proposed request is not a completed change.
Verify required credentials, indexed content, and outstanding ingestion steps, then test representative inputs. Creating a configuration is not the same as validating the finished workflow.
Review what io proposes
Review the operation, target, and body against what you requested. Approval does not replace checking permissions, credentials, or resulting behavior.
Review agent change sets
An agent update uses PATCH /v2/agents/{agent_key} and a partial change set, not a full replacement. The Update agent operation is the reference for its fields.
| The agent update contains | Effect |
|---|---|
| An omitted field | The existing field is preserved. |
null for a nullable field | The field is cleared or reset as specified by Update agent. Do not assume a non-nullable field accepts null. |
null for one entry in tool_configurations, skills, or steps | The named entry is deleted. |
null for the entire tool_configurations or skills map | All entries in that map are cleared. |
For a named removal, check the specific map entry rather than approving a whole-map clear. Consult the operation's reference for other fields or other resource types; do not assume every update has identical semantics.
Review full text replacements
Including a lambda tool's code, an instruction template, or a skill's content in its change set replaces that string in full. Compare the full proposed value with the current value, even when you requested a small edit.
Specify the part of a long instruction or block of code you want changed. Check for dropped retry logic, edge cases, or text outside the requested change. Avoid an unbounded request to "clean this up" when you intend a narrow edit.
When Review and edit is unavailable
Console supports Review and edit for resource proposals including corpus creation and updates. Lambda-tool update cards and generic API-call cards do not offer that editor action.
When it is unavailable, inspect View proposed body. Cancel an incorrect proposal and ask io for a revision instead of accepting it.
Where io stops
| Boundary | Your responsibility |
|---|---|
| Proposed changes | Inspect the specific proposal. Broad agreement earlier in a session is not a review of its request body. |
| High-stakes scope | Specify permitted actions and limits for legal, medical, financial, payment, PII, or irreversible external actions. Do not leave that authority to an unspecified default. |
| Credentials | Supply the actual secret values behind references such as {"$ref": "agent.secrets.<name>"}. See Secrets. |
| Permissions | Use an account or API key with appropriate access. See API key management. |
| Content | Check that the required data is indexed. A corpus configuration is not indexed content. |
| Production readiness | Review tool access, corpus selection, instructions, and LLM choice, and test representative inputs. |
Operate an agent after it ships
Diagnose a session
Provide the agent key and session key. Ask io for the failing step, the tool error if present, and the evidence supporting its explanation.
| Question | Evidence to inspect |
|---|---|
| What happened, which tool ran, what did it return? | The durable session event log, pairing tool inputs and outputs by their call ID. |
| Which run failed or took too long? | Agent trace summaries, filtered by agent, session, status, error type, tool name, or duration. |
| What happened within a run, and what did the model see? | Trace spans; request include_content=true when inspecting span content such as messages or tool arguments. |
Trace listings contain summaries, not the underlying messages or tool inputs and outputs. Ask for a focused explanation rather than a dump of raw payloads. Console also provides an Observability view for metrics and traces.
Watch usage and performance
In Console, io can offer a card that opens live charts for usage, latency, error rates, or token consumption. The card supports the last hour, 24 hours, 7 days, or 30 days, optionally scoped to one agent.
The metrics tab fetches data when you open it. Its values can differ from numbers quoted earlier in the session. Use metric names from the metrics catalog rather than assuming a name exists.
Task examples
For task examples, see What you can ask io.
FAQs
Can io inspect a resource without my opening it in Console?
Yes, within your permissions. Supply its name or key, and verify that any resulting proposal targets the intended resource. An ambiguous name can require clarification.
How do I check a proposal that removes just one tool?
In an agent change set, the named entry in tool_configurations should be set to null. Setting the entire map to null clears all tools. Review the actual body and consult the agent-update table.
Why might one task produce several approval cards?
A task can involve several resources or successive updates. Check the target and operation on each proposal. Multiple cards are not evidence of completion; verify the resulting resources and remaining work.
What should I provide when asking why an agent failed?
Provide the agent and session keys and state what you expected versus what happened. Ask for an explanation tied to session events or trace/span evidence, not a general troubleshooting answer.
Can I use an agent in production as soon as io creates it?
Creation alone does not validate the workflow. Check credentials, indexed content, permissions, tools, and behavior on representative inputs. If the task had several steps, establish which ones actually completed.