Getting started
im-sdk is the Python SDK your agent calls at runtime. It gives you typed
access to the capabilities the Portal granted your agent — LLMs, embeddings,
document parsing, web search/crawl, and connected HTTP services — through one
ImCore client.
The fastest way to a working agent is to scaffold one:
im-cli new python-llm my-agent && cd my-agentThat ships a runnable main.py, a pyproject.toml + frozen uv.lock that
resolve im-sdk from the public in·manas index, and a .im/io.json describing
the agent's inputs/output. The rest of this page
explains what that code does so you can write your own. For the full list of
resources, methods, and return types, see Capabilities.
The runner contract
When the platform runs your agent, the agent-runner:
- injects identity into the environment per execution —
AGENT_ID,AGENT_VERSION_ID,EXECUTION_UUID,WORKSPACE_ID, andIM_CHECKER_URL(the address of the service the SDK authorizes against) — so you never hardcode it. You don't provide the agent's secret yourself:from_env()applies the right default for the current stack, and per-agent credentials are handled by the platform; - appends your inputs as a single
--input '<json>'argument; - treats stdout as the agent's output — it
json.loads()whatever you print, so print only the final result there; - collects progress from the SDK's
log()helper (this is what shows up in the Console tab,im-cli logs, and the liveim-cli runstream).
The quick path — @im_agent
The SDK ships a decorator that owns the whole boundary: it builds and authorizes
the client from the environment, reads the input, opens a trace, records your
return value as both the trace output and the stdout JSON, and maps ImError
to a non-zero exit. Most agents only need this:
import asyncio
from im_sdk import ImCore, im_agent
@im_agent("my-agent") # the Langfuse trace name
async def main(core: ImCore, data: dict) -> str:
prompt = str(data.get("prompt", "Say hello."))
result = await core.llm.call(
messages=[{"role": "user", "content": prompt}],
alias="gpt-mini", # an `llm` alias granted to this agent
)
return result.text # → trace output + stdout JSON
if __name__ == "__main__":
asyncio.run(main())data is read_input() (the real --input payload) falling back to
example_input() (the example.inputs block in .im/io.json) so the agent
runs locally with no arguments.
The explicit form
Reach for the explicit lifecycle when you need finer control — multiple
outputs, a custom trace input, mid-run set_output, or partial-failure
handling. This is what the python-llm scaffold spells out:
import asyncio, json, sys
from im_sdk import ImCore, ImError, example_input, read_input
from im_sdk.tracing import async_trace_run, log
async def main() -> None:
data = read_input() or example_input()
prompt = str(data.get("prompt", "Say hello."))
core = ImCore.from_env() # reads AGENT_ID / WORKSPACE_ID / IM_CHECKER_URL / …
output = ""
try:
async with core: # authorizes; the manifest gates every call
log(f"authorized (kind={core.kind})", level="info")
async with async_trace_run("my-agent", input={"prompt": prompt}) as trace:
result = await core.llm.call(
messages=[{"role": "user", "content": prompt}],
alias="gpt-mini",
)
output = result.text
trace.set_output(output)
except ImError as exc:
log(f"in·manas error: {exc}", level="error")
print(f"in·manas error: {type(exc).__name__}: {exc}", file=sys.stderr)
raise SystemExit(1) from None
print(json.dumps(output)) # stdout = the output ONLY
if __name__ == "__main__":
asyncio.run(main())ImCore.from_env() is the recommended constructor. You can still build it
explicitly — ImCore(agent_id=…, workspace_id=…, base_url=…), keyword arguments only
— but from_env() applies the correct env-var fallbacks for you.
You never set AGENT_SECRET yourself. The runner injects a fresh one for every run
(next to EXECUTION_UUID), the SDK reads it from the environment, and Portal only
authorizes a caller that holds the secret of a run that is still in progress. Outside a
runner — an example started by hand against your local stack — there is no secret, and
only a local stack accepts that.
Calling capabilities
Everything goes through the core client, and every call resolves against a
capability the agent was granted in the Portal. There are two addressing
styles:
- Model-addressed (
llm,embedding) — passalias=, the model alias name. The gateway resolves the alias to a provider and backend model. - Service-addressed (
document_parse,web_search,web_crawler,web_fetch,data,object_store,vector,mcp,http_capability) — passservice=, the connected-service name.
Never guess names — read what this agent may use with im-cli agent models (the
aliases) and im-cli agent services (the connected services).
# LLM — alias-addressed
result = await core.llm.call(messages=[...], alias="gpt-mini")
text = result.text
# Embeddings — alias-addressed; returns a ResourceResult
result = await core.embedding.embed(["a", "b"], alias="text-embed")
vectors = result.output.vectors # list[list[float]]
# Document parsing — service-addressed
result = await core.document_parse.partition(service="unstructured", file="/path/to.pdf")
elements = result.output.elements
# Web search — service-addressed
result = await core.web_search.search(service="tavily", query="latest in·manas release")
# Fetch a URL you chose yourself — service-addressed; the service is the policy
result = await core.web_fetch.fetch("web", "https://example.org/feed.xml")
body = result.text # FetchOutput.content_text
# MCP tools — service-addressed; you may list and call only the tools granted to the agent
tools = await core.mcp.list_tools("acme-tools")
result = await core.mcp.call_tool("acme-tools", "search_docs", {"q": "refund policy"})
if not result.output.is_error: # a tool that failed is a result, not an exception
answer = result.output.textEvery call returns a canonical ResourceResult — result.text for the
text answer, result.output for the typed variant (LlmOutput,
EmbeddingOutput, SearchOutput, DocumentOutput, FetchOutput, …), plus
result.usage,
result.model, and result.citations. Cost is not among them for most calls: the
Gateway owns billing and freezes it on the execution trace, so result.cost is set
only by self-pricing drivers. See
Capabilities for the full method and return-type reference.
Configuration and credentials come from the organization, not from the code:
core.vars["KEY"] reads a granted variable, and core.secret("KEY") returns a
SecretRef — a placeholder string the gateway replaces with the secret's value in
a call to a connected service, so your code never holds it. See
Variables & secrets.
Tracing & logs
Import these from im_sdk.tracing (also re-exported from im_sdk):
log(message, level=...)— emits a progress line (info/warn/error/debug). This is your Console-tab output; it's a no-op outside the runner and is filtered byIM_LOG_LEVEL.async_trace_run(name, input=...)/trace_run(...)(sync) — wraps the run so the Portal/Langfuse trace gets proper I/O; calltrace.set_output(...)before the block exits. Nesting a second boundary raises.@observe(name=...)— decorate a helper so its calls nest under a named span.mark(name, metadata=...)— pin a zero-duration checkpoint on the trace.
@im_agent sets up the outer async_trace_run for you, so inside it you only
need @observe / mark for structure.
Errors
All SDK failures derive from ImError. Catch it at the top of your entry point,
log it, and exit non-zero so the execution is recorded as failed with a
readable message (@im_agent does this for you).
The gateway classifies every failure into a typed taxonomy, and since SDK 0.8.11
the SDK re-raises that same type — except ImQuotaError: matches a real rate
limit, and the exception carries structured attributes: exc.code (a
ImErrorCode, e.g. QUOTA_EXCEEDED) and exc.context (a dict with details
like the provider or the offending parameter), so you can branch without parsing
message text:
| Exception | Meaning |
|---|---|
ImAuthError | Authentication failed (401). |
ImForbiddenError | Not permitted by the manifest (403). |
ImManifestError | The manifest rejected the call (422). |
ImValidationError | Invalid request payload (422). |
ImQuotaError | Quota / rate limit exceeded (429). |
ImGuardrailBlockedError | Your organization's guardrail policy refused the content (403). A ImForbiddenError; exc.context["check"] names the check and ["phase"] says whether it judged the request or the response. |
ImGuardrailUnavailableError | A guardrail could not reach a verdict, so the call was refused rather than run unchecked (503). |
ImResourceError | Upstream provider failure (502) — parent of ImTimeoutError (504) and ImDriverError. Check exc.code before retrying: RESOURCE_UPSTREAM_FAILED is the provider having a bad moment and is worth another attempt, while RESOURCE_MISCONFIGURED means the platform cannot dispatch the call at all and will fail identically until an operator fixes the deployment. |
ImTransportError / ImGatewayError | Fallbacks: connection/protocol failure talking to the gateway, or a structured gateway error of a type the SDK doesn't recognize. |
A per-call timeout surfaces as ImTimeoutError (the gateway's typed 504):
the SDK deliberately waits slightly longer than the gateway, so you get that
instead of a bare ImTransportError. Note that for llm and embedding a
per-call timeout can only tighten the deadline — the gateway caps those
calls at its own ceiling (900 s by default), so a larger value is silently
capped, never extended. With no per-call timeout, the SDK transport waits
925 s so that 504 still wins over a generic client timeout.
Before SDK 0.8.11 every gateway failure arrived flattened into
ImTransportError (HTTP ≥ 500) or ImGatewayError (< 500). Code that catches
those two specifically should switch to the typed subclasses or to the ImError
base, which has always caught everything.
Installing the SDK
im-sdk isn't on PyPI. It is published to in·manas's own PEP 503 index at
https://downloads.mgt-platform.com/simple/, which is public — no
credential, no token, nothing to export. pip install im-sdk on its own
resolves nothing, because the index has to be named.
In a project, name it in pyproject.toml (this is what the scaffolds ship):
[[tool.uv.index]]
name = "in-manas"
url = "https://downloads.mgt-platform.com/simple/"
explicit = true
[tool.uv.sources]
im-sdk = { index = "in-manas" }Then uv lock resolves and pins the latest published im-sdk, and im-cli push uploads pyproject.toml + uv.lock together — the agent slot installs
with uv sync --locked and fetches the SDK from the same public index your
laptop did. Your other dependencies keep resolving from PyPI as usual.
For a throwaway check outside a project, name the index on the command line instead — a convenience, never project configuration:
uv pip install --extra-index-url https://downloads.mgt-platform.com/simple/ im-sdk